ADR-020 — Coverage Dashboard Strategy

Status

Draft

Context

Coverage is the ratio of active assignment hours to required position hours — four discrete states (VACANT 0 %, PARTIAL 1-99 %, COVERED 100 %, OVER_COVERED >100 %), computed at read time, never persisted ([[adr-011-weekly-only-compute|ADR-011]]). Hour-color totalization rules are defined in [[adr-001-c-hour-color-vocabulary|ADR-001-c]].

The Coverage Dashboard ([[PRD]] §6.6) is an executive view that aggregates coverage from UNIT leaves upward through the org hierarchy (Unit → Service → Department → Clinic; [[adr-018-orgunit-demand-scope|ADR-018]]). It must show global KPIs (total positions, average coverage %, hours deficit), per-unit breakdowns by coverage state, hierarchical rollups at every org level, and configurable alert thresholds ([[adr-016-capacity-planning-patterns|ADR-016]] §2).

The current GET /api/v1/demand/coverage-summary/ endpoint returns a flat by_unit array with per-unit metrics and global totals. API.md delegates hierarchical aggregation to the frontend via parent_id chains. A minimal /coverage page renders global KPIs and a flat p-table sorted by worst coverage.

Open design questions that block acceptance: (1) server-side vs client-side hierarchical aggregation, (2) caching strategy at scale (500+ positions), (3) hardcoded vs per-org-unit alert thresholds for MVP, (4) refresh strategy (manual, interval, or WebSocket), (5) tree visualization component (p-treetable, drill-down, or grouped flat table).

Decision

Pending.

Interim baseline. The current implementation is a minimal placeholder: global KPIs + flat per-unit table using coverage-summary. It will be replaced or extended once the open questions are resolved.

Consequences

Pending — will cover aggregation approach, new endpoints or models, caching, and frontend component architecture.