cve-dashboard/.kiro/specs/vcl-aggregated-burndown/requirements.md

Requirements Document

Introduction

This feature adds an aggregated (cross-vertical) burndown forecast chart to the main CCP Metrics overview page. Currently, burndown forecasts only exist at the per-vertical drill-down level — when a user clicks into a specific vertical (e.g., NTS_AEO), they see that vertical's burndown showing blockers, devices with dates, and monthly projected remediation. This feature rolls up the same burndown concept across ALL verticals and displays it on the overview page alongside the existing Stats Bar, Compliance Trend chart, and Non-Compliant Status donut chart.

Glossary

• Aggregated_Burndown_API: The backend endpoint that computes burndown forecast data across all verticals by querying active non-compliant devices from compliance_items where vertical IS NOT NULL.
• Burndown_Chart: A Recharts-based bar chart component that visualizes monthly projected remediation counts and cumulative remaining non-compliant devices across all verticals.
• Blocker: A non-compliant device in compliance_items with status = 'active' and resolution_date IS NULL — no committed remediation timeline exists.
• In_Progress_Device: A non-compliant device in compliance_items with status = 'active' and a non-null resolution_date — a target remediation date has been set.
• Monthly_Bucket: A grouping of in-progress devices by the month portion (YYYY-MM) of their resolution_date, representing how many devices are expected to be remediated in that month.
• Projected_Clear_Date: The earliest month by which all in-progress devices (those with resolution dates) are projected to be remediated, assuming blockers remain unresolved.
• Overview_Page: The main CCP Metrics page (CCPMetricsPage.js) that displays aggregated cross-vertical statistics before any vertical drill-down is selected.

Requirements

Requirement 1: Aggregated Burndown API Endpoint

User Story: As a compliance analyst, I want a single API endpoint that returns burndown forecast data aggregated across all verticals, so that the overview page can display a cross-organizational remediation projection without requiring multiple per-vertical API calls.

Acceptance Criteria

1. WHEN a GET request is made to /api/compliance/vcl-multi/burndown, THE Aggregated_Burndown_API SHALL return a JSON response containing total_non_compliant, blockers, with_dates, monthly_forecast, and projected_clear_date fields.
2. THE Aggregated_Burndown_API SHALL compute total_non_compliant as the count of distinct hostnames in compliance_items where vertical IS NOT NULL and status = 'active'.
3. THE Aggregated_Burndown_API SHALL compute blockers as the count of distinct hostnames where resolution_date IS NULL among active non-compliant devices across all verticals.
4. THE Aggregated_Burndown_API SHALL compute with_dates as the count of distinct hostnames where resolution_date IS NOT NULL among active non-compliant devices across all verticals.
5. THE Aggregated_Burndown_API SHALL compute monthly_forecast by bucketing in-progress devices into Monthly_Buckets based on the YYYY-MM portion of their resolution_date, with each bucket containing the count of devices projected to be remediated in that month.
6. THE Aggregated_Burndown_API SHALL deduplicate devices by hostname before computing burndown totals — a device appearing in multiple metrics counts once, using the earliest non-null resolution_date across its metric entries.
7. THE Aggregated_Burndown_API SHALL return projected_clear_date as the last month in the sorted monthly forecast when all in-progress devices have been accounted for, or null when blockers exist.
8. WHEN no active non-compliant devices exist across any vertical, THE Aggregated_Burndown_API SHALL return total_non_compliant: 0, blockers: 0, with_dates: 0, monthly_forecast: {}, and projected_clear_date: null.
9. THE Aggregated_Burndown_API SHALL require authentication via requireAuth() middleware.

Requirement 2: Aggregated Burndown Computation Logic

User Story: As a developer, I want a pure helper function that computes aggregated burndown from a set of device objects, so that the computation is testable in isolation and reusable.

Acceptance Criteria

1. THE computeAggregatedBurndown helper function SHALL accept an array of device objects (each with hostname and resolution_date fields) and return an object with total, blockers, with_dates, monthly, projection, and projected_clear_date fields.
2. FOR ALL valid input arrays, THE computeAggregatedBurndown function SHALL satisfy the invariant: blockers + with_dates = total.
3. FOR ALL valid input arrays, THE computeAggregatedBurndown function SHALL satisfy the invariant: the sum of all values in monthly equals with_dates.
4. THE computeAggregatedBurndown function SHALL produce monthly buckets sorted chronologically by month key (YYYY-MM format).
5. THE computeAggregatedBurndown function SHALL compute projection as a cumulative remaining count per month — starting from total and subtracting each month's remediated count in chronological order.
6. WHEN the input array is empty, THE computeAggregatedBurndown function SHALL return total: 0, blockers: 0, with_dates: 0, monthly: {}, projection: {}, and projected_clear_date: null.
7. WHEN all devices have resolution_date = null, THE computeAggregatedBurndown function SHALL return blockers equal to total, with_dates: 0, monthly: {}, and projected_clear_date: null.

Requirement 3: Burndown Chart Frontend Component

User Story: As a senior leader viewing the CCP Metrics overview page, I want to see an aggregated burndown forecast chart showing when non-compliant devices across all verticals are projected to be remediated, so that I can assess organizational remediation progress at a glance.

Acceptance Criteria

1. THE Burndown_Chart SHALL be displayed on the Overview_Page below the Compliance Trend chart and Non-Compliant Status donut chart section.
2. THE Burndown_Chart SHALL display a bar chart with one bar per Monthly_Bucket, where the bar height represents the count of devices projected to be remediated in that month.
3. THE Burndown_Chart SHALL display a summary header showing the total non-compliant count, blocker count, in-progress count, and projected clear date.
4. THE Burndown_Chart SHALL use the Recharts BarChart component with styling consistent with the existing Compliance Trend chart (dark background, teal/purple color palette, monospace axis labels).
5. WHEN the Aggregated_Burndown_API returns total_non_compliant: 0, THE Burndown_Chart SHALL display a message indicating no non-compliant devices exist rather than rendering an empty chart.
6. WHEN the Aggregated_Burndown_API returns monthly_forecast with zero entries but blockers > 0, THE Burndown_Chart SHALL display the blocker count with a message indicating all non-compliant devices lack remediation dates.
7. THE Burndown_Chart SHALL fetch data from the Aggregated_Burndown_API on page load and display a loading indicator while the request is in flight.
8. IF the Aggregated_Burndown_API request fails, THEN THE Burndown_Chart SHALL display an inline error message consistent with the existing error display pattern on the Overview_Page.

Requirement 4: Burndown Data Consistency

User Story: As a compliance analyst, I want the aggregated burndown numbers to be consistent with the per-vertical burndown data, so that I can trust the overview numbers match the sum of individual verticals.

Acceptance Criteria

1. FOR ALL sets of active non-compliant devices, THE Aggregated_Burndown_API total_non_compliant SHALL equal the sum of total_non_compliant values returned by each individual per-vertical burndown endpoint (GET /api/compliance/vcl-multi/vertical/:code/burndown).
2. FOR ALL sets of active non-compliant devices, THE Aggregated_Burndown_API blockers SHALL equal the sum of blockers values returned by each individual per-vertical burndown endpoint.
3. FOR ALL sets of active non-compliant devices, THE Aggregated_Burndown_API with_dates SHALL equal the sum of with_dates values returned by each individual per-vertical burndown endpoint.
4. FOR ALL monthly buckets, THE Aggregated_Burndown_API monthly forecast count for a given month SHALL equal the sum of that month's forecast count across all per-vertical burndown responses.

Requirement 5: Per-Vertical Contribution Breakdown

User Story: As a compliance analyst, I want to see which verticals contribute the most to the aggregated burndown, so that I can identify which organizations need the most attention for remediation planning.

Acceptance Criteria

1. THE Aggregated_Burndown_API response SHALL include a by_vertical array containing per-vertical breakdowns with fields: vertical, total, blockers, with_dates.
2. THE by_vertical array SHALL be sorted in descending order by total (most non-compliant devices first).
3. THE Burndown_Chart component SHALL display the per-vertical breakdown below the bar chart as a compact summary table showing each vertical's contribution to the overall burndown.
4. WHEN a vertical has zero active non-compliant devices, THE Aggregated_Burndown_API SHALL omit that vertical from the by_vertical array.