state-hub/docs/architecture/state-hub_v0.1.md

---
id: state-hub-architecture
title: "State Hub architecture"
status: proposed
owner: state-hub
revision: "draft-3"
version: "0.1"
last_reviewed: "2026-08-31"
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 | 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.

---

## 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. |