tegwick
5dd04dcb3d
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a053ff-1d6f-7fe2-ac1c-a6eb40a42a0c
159 lines
3.9 KiB
Markdown
159 lines
3.9 KiB
Markdown
---
|
||
id: state-hub-architecture
|
||
title: "State Hub architecture"
|
||
status: proposed
|
||
owner: state-hub
|
||
revision: "draft-2"
|
||
version: "0.1"
|
||
last_reviewed: "2026-08-19"
|
||
review_interval: 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
|
||
|
||
1. Rebuildability from git.
|
||
2. Hub never becomes the origin of work.
|
||
3. 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. |
|