tegwick
5dd04dcb3d
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a053ff-1d6f-7fe2-ac1c-a6eb40a42a0c
3.9 KiB
| id | title | status | owner | revision | version | last_reviewed | review_interval |
|---|---|---|---|---|---|---|---|
| state-hub-architecture | State Hub architecture | proposed | state-hub | draft-2 | 0.1 | 2026-08-19 | 6m |
State Hub — Software Architecture Documentation (arc42)
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.
1. Introduction 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. |
2. Architecture Constraints
N/A for this stub — retirement program is the binding constraint.
3. System 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).
4. Solution 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).
5. Building Block View
5.1 Level 1 – System/Top-Level
N/A for this stub.
6. Runtime View
N/A for this stub.
7. Deployment View
N/A for this stub.
8. Cross-Cutting Concepts
N/A for this stub.
9. Architecture 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 | Hub is a read model. Published /adr/custodian-workplans-as-repo-artefacts/v1/. |
CUST-ADR-003 |
accepted | How the cache invalidates. |
CUST-ADR-007 |
accepted | One writer of workplan UUIDs. |
CUST-ADR-010 |
proposed | Two kinds of hub data. |
| 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.
10. Quality Requirements
N/A for this stub.
11. Risks and Technical Debt
N/A for this stub. Residual: this workstation cannot mint registrar UUIDs.
12. Glossary
| 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. |