About this document
First-wave arc42 for State Hub, the estate's live coordination read-model. This service is in active retirement planning; new permanent ownership should not land here. Chapter 9 points at the estate ADRs that still bind it.
01Introduction and Goals
State Hub is a queryable, auditable memory of work: domains, repos, workplans, tasks, decisions, progress. Files remain the origin. The hub is derived state (custodian ADR-001, ADR-003).
It remains operational until retirement gates in prj-state-hub-retirement are met. Replacement ownership is moving toward repo-manager and hub-core.
1.1 Requirements Overview
- Rebuild coordination state from registered repository files.
- Deterministic UUIDv5 work-record identifiers (ADR-007). Any instance may reconcile the same repository; the canonical record id produces the same database key and writeback bytes on every instance.
- Preserve compatibility; do not take new permanent architectural ownership.
1.2 Quality Goals
- Rebuildability from git.
- Hub never becomes the origin of work.
- Extraction paths stay open.
1.3 Stakeholders
| Role | Concern |
|---|---|
| state-hub | Live read-model during retirement. |
| the-custodian | Estate rules the hub must not invert. |
| repo-manager | Incoming consistency / repo representation. |
| product repos | Workplan files the hub indexes. |
02Architecture Constraints
N/A for this stub — retirement program is the binding constraint.
03System Scope and Context
In: indexing workplans/tasks/decisions, consistency rebuild, query API and dashboard used today. Out: being the source of work items; new cross-domain capabilities; publication of policy (policy-nexus).
3.1 Business Context
Files are excellent for canon and provenance. The estate still needs a live query surface while retirement proceeds.
3.2 Technical Context
Inputs: workplan markdown via fix-consistency. Outputs: HTTP/MCP APIs. Neighbours: every registered repo, activity-core (ops runs), policy-nexus (does not index the hub).
04Solution Strategy
N/A for this stub. The strategy is already in the estate ADRs: files first, materialized derived state, single registrar, local cache vs authority (ADR-010, proposed).
05Building Block View
5.1 Level 1 – System/Top-Level
N/A for this stub.
06Runtime View
N/A for this stub.
07Deployment View
N/A for this stub.
08Cross-Cutting Concepts
N/A for this stub.
09Architecture Decisions
Estate-wide binding decisions live in the-custodian and are listed on the estate map. Service-local implementation decisions live in docs/adr/ and do not supersede the estate decisions:
| Estate ADR | Status | Why it binds this system |
|---|---|---|
CUST-ADR-001 | accepted | File-backed work originates in repositories; the Hub projects it. Published /adr/custodian-workplans-as-repo-artefacts/v1/. |
CUST-ADR-003 | accepted | How derived state invalidates; ADR-012 supplies commit provenance. |
CUST-ADR-007 | accepted | Namespace-aware identity and deterministic work-record UUIDs. |
CUST-ADR-010 | proposed | Two kinds of hub data. |
CUST-ADR-011 | proposed | Namespace and reconciliation limits. |
CUST-ADR-012 | accepted | Forge projection baseline and preliminary overlays. |
| Local ADR | Status | Scope |
|---|---|---|
STATE-ADR-001 | accepted | Repository identity and recovery contract for canonical-name changes. |
Do not treat a State Hub /decisions row as the published ADR.
10Quality Requirements
N/A for this stub.
11Risks and Technical Debt
N/A for this stub. Residual: this workstation cannot mint registrar UUIDs.
12Glossary
| Term | Meaning |
|---|---|
| Read model | Derived index; never the origin. |
| Registrar | The single instance allowed to mint workplan UUIDs. |
| Retirement | Coordinated move of capabilities out of this repo. |