state-hub/dashboard/src/docs/overview.md

---
title: Overview — Reference
---

# Overview — Reference

The Overview page is the operational home screen of the Custodian State Hub.
It shows the live health of the entire ecosystem at a glance — active work,
blocking decisions, and system-derived next-step suggestions.

---

## Sections

### Open Workplans by Repository

A horizontal stacked bar chart showing workplans grouped by domain and then
by repository. Each bar is broken into four task-status segments:

| Colour | Segment |
|--------|---------|
| green | done |
| purple | progress |
| orange | wait |
| light grey | todo |

Above the chart:

- **Mode selector** — lifecycle, health, or recently-changed windows (with
  matching workplan counts in each option).
- **Text filter** — case-insensitive substring match on title, repository,
  domain, workplan filename, and owner. Useful when many rows share a mode.

The left axis shows the `domain / repository` label once per repository group.
The `done/total` count is printed to the right of each bar. Workplans with no
tasks yet show a grey "— no tasks yet" label.

Hovering a bar shows the repository, domain, and backing workplan filename when
the workplan is file-backed. Clicking a bar or its label opens the workplan
drilldown page with the attached task list.

### Contribution & SBOM Health

Three summary cards linked to the Contributions and SBOM pages:

| Card | Shows |
|------|-------|
| **Contributions** | Total artifact count; orange warning if any are awaiting upstream response |
| **Licence Risk** | Count of SBOM packages with copyleft licences in direct dependencies |
| **SBOM** | Breakdown by contribution type (BR / FR / EP / UPR) |

### Status

Four metric cards:

| Card | Meaning |
|------|---------|
| **Active Workplans** | Count of active/blocked execution workplans |
| **Blocking Decisions** | Pending decisions with status `open` or `escalated` — orange border if > 0 |
| **Blocked Tasks** | Click to expand the list with blocking reasons |
| **Events Today** | Progress events created on today's date |

### What's next?

System-derived action suggestions from `GET /state/next_steps`. Suggestions are
generated when a decision is resolved or a workplan dependency is cleared, and
they point to the first open task in the relevant workplan. These are derived
on request and never persisted.

### Blocking Decisions

Inline resolution form for each pending decision. Expand a card, enter a
rationale and "decided by" name, and click **Record & close**. The decision is
resolved via `POST /decisions/{id}/resolve` and disappears from the list
without a page reload.

### Registered Projects

Table of projects registered with `make register-project`, sourced from
`milestone` progress events whose summary starts with
`"Project registered with State Hub:"`.

### Recent Activity

Last 20 progress events across all domains, showing time, event type, author,
and summary.

---

## Data source

Polls `GET /state/overview` every **60 seconds**. This endpoint is a bounded
dashboard read model: it returns summary totals, recent activity, registration
milestones, SBOM totals, and chart-ready workplan rows with task counts already
aggregated server-side.

The page keeps the last successful overview response visible if a refresh times
out, and marks the view stale instead of clearing the dashboard. Blocking
decisions are fetched separately via `GET /decisions/?decision_type=pending`
and only re-fetched after a successful resolve action — this prevents the inline
form from being wiped on every poll.