coulomb/state-hub
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
state-hub/docs/architecture/state-hub_v0.1.md
tegwick 8754983a0d
All checks were successful
CI Smoke / host-smoke (push) Successful in 1s
Details
CI Smoke / container-smoke (push) Successful in 1s
Details
docs: define repository rename identity contract 
Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a049a4-ee9f-78e1-9d66-2cb0f9bea3e3
2026-08-28 21:24:50 +02:00

3.8 KiB
Raw Blame History

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.
  • One identifier registrar (ADR-007). This workstation is not it.
  • 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.