04360cc4bc
New feature: multi-file per-vertical compliance xlsx upload with scoped resolution logic, executive-level aggregated reporting, and drill-down by vertical and metric. Supports daily upload cadence and batch commit. Backend: - Migration: add vertical column to compliance_items/uploads, create vcl_multi_vertical_summary table - New route module: routes/vclMultiVertical.js with preview, commit, stats, trend, metric drill-down, device list, and burndown endpoints - New helpers: parseVerticalFilename(), computeVerticalBurndown() - Vertical-scoped resolution: uploading one vertical never resolves items from other verticals Frontend: - CCPMetricsPage with stats bar, trend chart, donut, vertical table - Drill-down: vertical -> metrics by category -> device list - Per-vertical burndown forecast chart - MultiVerticalUploadModal: multi-file drag-drop, batch preview, commit - Nav entry: CCP Metrics (Building2 icon) Docs: - Design brief for stakeholder meeting (docs/vcl-multi-vertical-design-brief.md)
185 lines
10 KiB
Markdown
185 lines
10 KiB
Markdown
# VCL Multi-Vertical Upload — Design Brief
|
||
|
||
## Purpose
|
||
|
||
This document summarizes the design decisions and architectural choices for the VCL Multi-Vertical Upload feature. It is intended as a reference for presenting the approach to stakeholders and the compliance team.
|
||
|
||
---
|
||
|
||
## What We Are Building
|
||
|
||
A new upload flow on the STEAM Security Dashboard that accepts multiple per-vertical compliance xlsx files (one per organizational vertical), ingests them with vertical-scoped resolution logic, and generates an executive-level VCL compliance report across all organizations — with drill-down by vertical and by metric.
|
||
|
||
This is a POC. The compliance team currently exports data from CyberMetrics as xlsx files on a 24-hour cycle. This feature lets them upload those files and generate the same reports they currently build manually in PowerPoint/Excel for senior leadership.
|
||
|
||
---
|
||
|
||
## The Problem It Solves
|
||
|
||
Today the compliance team has 14 separate xlsx files — one per vertical (NTS_AEO, SDIT_CISO, TSI, etc.). The existing dashboard upload flow accepts a single consolidated file and treats it as the complete compliance state. If you upload just one vertical's file, the system incorrectly marks every device from the other 13 verticals as "resolved."
|
||
|
||
There is no automated way to:
|
||
- Ingest all 14 files and produce a unified report
|
||
- Drill down from the organizational view into specific metrics and devices
|
||
- Generate burndown forecasts across verticals
|
||
|
||
---
|
||
|
||
## Key Architectural Decisions
|
||
|
||
### 1. Vertical-Scoped Resolution
|
||
|
||
**Decision:** When a file for vertical X is committed, only items belonging to vertical X are evaluated for resolution. All other verticals are untouched.
|
||
|
||
**Why:** This is the fundamental change that makes per-vertical uploads safe. Without it, uploading one file would destroy data from the other 13 verticals.
|
||
|
||
**Implication:** Verticals are independent. You can upload NTS_AEO on Monday and SDIT_CISO on Wednesday without interference. This also supports the daily upload cadence the compliance team wants.
|
||
|
||
### 2. Vertical Identity Comes From the Filename
|
||
|
||
**Decision:** The vertical code is extracted from the filename pattern `<VERTICAL>_YYYY_MM_DD.xlsx`, not from data inside the xlsx.
|
||
|
||
**Why:** The internal xlsx structure is identical across verticals — same Summary sheet, same metric detail sheets, same columns. The only differentiator is the filename. This also means the Python parser requires zero changes.
|
||
|
||
**Implication:** Filenames must follow the convention. If they don't, the system flags them as "unrecognized" and the user can manually assign a vertical. This is a reasonable tradeoff for a POC.
|
||
|
||
### 3. Separate From Existing AEO Upload
|
||
|
||
**Decision:** This is a new flow with its own endpoints (`/api/compliance/vcl-multi/...`), its own UI page, and its own nav entry. The existing AEO compliance upload is unchanged.
|
||
|
||
**Why:**
|
||
- The existing flow works for the STEAM/ACCESS-ENG team's day-to-day operations
|
||
- The compliance team may deploy this on a separate instance to experiment without affecting production
|
||
- Different user groups with different needs — engineers vs. compliance analysts vs. senior leadership
|
||
|
||
**Implication:** There are now two ways to upload compliance data. They coexist via the `vertical` column — existing AEO data has `vertical = NULL`, multi-vertical data has a vertical code. The VCL report page can aggregate either or both.
|
||
|
||
### 4. Two-Dimensional Grouping (Vertical + Team)
|
||
|
||
**Decision:** `vertical` and `team` are separate fields. Vertical is the organizational unit (NTS_AEO, SDIT_CISO). Team is the sub-team within a vertical (STEAM, ACCESS-ENG, ACCESS-OPS).
|
||
|
||
**Why:** NTS_AEO contains multiple sub-teams. Senior leadership wants to see the vertical-level view. The STEAM team wants to see their team-level view. Both are valid groupings on the same data.
|
||
|
||
**Implication:** The cross-organizational report groups by vertical. Drilling into NTS_AEO still shows the STEAM/ACCESS-ENG/ACCESS-OPS breakdown because that data exists in the "Team" column inside the xlsx.
|
||
|
||
### 5. Summary Sheet Data Stored Separately
|
||
|
||
**Decision:** The parsed Summary sheet (metric-level health data) is stored in a dedicated `vcl_multi_vertical_summary` table, not just as JSON on the upload record.
|
||
|
||
**Why:** The metric drill-down view needs to query per-metric compliance percentages and targets efficiently. Storing structured rows enables filtering, sorting, and aggregation at the database level rather than parsing JSON blobs in application code.
|
||
|
||
**Implication:** Slightly more storage, but enables fast queries like "show me all metrics below target across all verticals" without full-table scans.
|
||
|
||
### 6. Batch Upload With Atomic Commit
|
||
|
||
**Decision:** All files in a batch are committed in a single database transaction. If any file fails, the entire batch rolls back.
|
||
|
||
**Why:** Partial commits would leave the report in an inconsistent state — some verticals updated, others stale. The compliance team uploads all 14 files together as a reporting cycle. It should either all succeed or all fail.
|
||
|
||
**Implication:** If one file has a parsing error, the user is shown the error in the preview phase (before commit). They can remove that file from the batch and commit the rest. Once they hit "Commit," it's all-or-nothing.
|
||
|
||
### 7. Daily Upload Support (Idempotent)
|
||
|
||
**Decision:** Re-uploading the same vertical on the same day produces the same final state as uploading it once. The system doesn't create duplicate records.
|
||
|
||
**Why:** CyberMetrics refreshes on a 24-hour cycle. The compliance team may want to upload daily to track movement. They shouldn't have to worry about "did I already upload today?"
|
||
|
||
**Implication:** The resolution logic uses `vertical + hostname + metric_id` as the identity key. Recurring items get their `seen_count` incremented and metadata updated. New items are inserted. Missing items are resolved. Same logic as today, just scoped to the vertical.
|
||
|
||
---
|
||
|
||
## Drill-Down Hierarchy
|
||
|
||
```
|
||
Executive Overview (all verticals aggregated)
|
||
│
|
||
├── Stats: 4200 devices, 90% compliant, target 95%
|
||
├── Trend: monthly compliance % with forecast
|
||
├── Donut: 30% blocked, 70% in-progress
|
||
│
|
||
└── Vertical Breakdown Table
|
||
│
|
||
├── NTS_AEO — 90% — 80 non-compliant — click to drill down
|
||
│ │
|
||
│ ├── Metric Breakdown
|
||
│ │ ├── 5.2.4 (Access & MFA) — 98.1% — 15 non-compliant
|
||
│ │ ├── 1.1.1 (Logging) — 85% — 120 non-compliant → click
|
||
│ │ │ └── Device list: hostname, IP, type, team, seen_count
|
||
│ │ └── ...
|
||
│ │
|
||
│ └── Burndown: 25 blockers, 55 with dates, projected clear Q3 2026
|
||
│
|
||
├── SDIT_CISO — 92% — 45 non-compliant
|
||
└── ...
|
||
```
|
||
|
||
---
|
||
|
||
## Burndown Forecast
|
||
|
||
The burndown forecast answers: "When will this vertical reach compliance?"
|
||
|
||
**How it works:**
|
||
1. Each non-compliant device can have a `resolution_date` set (target remediation date)
|
||
2. Devices with dates are bucketed by month → "20 devices expected remediated in June, 35 in July"
|
||
3. Devices without dates are counted as "blockers" — no committed timeline
|
||
4. The trend chart uses linear regression on 3+ months of actual data to project a forecast line
|
||
|
||
**What feeds it:**
|
||
- Resolution dates can be set manually (click device → set date) or via bulk upload (xlsx with Hostname + Resolution Date columns)
|
||
- The existing bulk upload flow on the VCL page already supports this
|
||
|
||
**What the compliance team sees:**
|
||
- Per-vertical: "NTS_AEO has 80 non-compliant, 25 are blockers, 55 have dates, projected clear by August 2026"
|
||
- Aggregated: trend line showing whether the organization is on track to hit 95% target
|
||
|
||
---
|
||
|
||
## What Does NOT Change
|
||
|
||
- Existing AEO compliance upload (single file) — unchanged
|
||
- Existing VCL report page (STEAM/ACCESS-ENG view) — unchanged
|
||
- Existing compliance_items table structure — only adds a nullable `vertical` column
|
||
- Python parser — reused as-is, no modifications
|
||
- Auth model — same groups (Admin, Standard_User) required for upload
|
||
|
||
---
|
||
|
||
## Deployment Options
|
||
|
||
| Option | Description |
|
||
|---|---|
|
||
| Same instance | Add the feature to the existing dashboard. Multi-vertical data coexists with AEO data via the `vertical` column. |
|
||
| Separate instance | Deploy a fresh instance with its own database. Compliance team experiments freely. No risk to dev/production data. |
|
||
| Later: API integration | Replace xlsx upload with direct CyberMetrics API calls. Backend endpoints stay the same — just a different client pushing data. |
|
||
|
||
The architecture supports all three without code changes. The `vertical` column and scoped resolution logic work regardless of deployment topology.
|
||
|
||
---
|
||
|
||
## Open Questions for the Meeting
|
||
|
||
1. **Vertical list** — Are the 14 verticals in the screenshot the complete set, or do new verticals get added periodically? (Affects whether we hardcode a list or keep it dynamic.)
|
||
|
||
2. **Target % per vertical** — Is the 95% target uniform across all verticals, or do different verticals have different targets?
|
||
|
||
3. **Access control** — Should the compliance team have their own user accounts with a specific role, or do they use existing Admin/Standard_User groups?
|
||
|
||
4. **Naming** — What should this page be called in the nav? "CCP Metrics", "VCL Multi-Vertical", "Compliance Reporting", something else?
|
||
|
||
5. **Retention** — How long should historical upload data be kept? (Affects trend chart depth and storage.)
|
||
|
||
---
|
||
|
||
## Timeline Estimate
|
||
|
||
| Phase | Scope | Effort |
|
||
|---|---|---|
|
||
| 1. Migration + backend endpoints | Schema changes, upload flow, scoped resolution, stats/trend/drill-down APIs | 2–3 days |
|
||
| 2. Frontend — upload modal | Multi-file drop, filename parsing, batch preview, commit | 1–2 days |
|
||
| 3. Frontend — report page | Stats bar, vertical table, trend chart, donut, drill-down views | 2–3 days |
|
||
| 4. Frontend — burndown | Per-vertical burndown chart, blocker counts, forecast | 1 day |
|
||
| 5. Testing + polish | Property tests, edge cases, error handling, loading states | 1 day |
|
||
|
||
Total: roughly 7–10 working days for the full POC.
|