state-hub/README.md

State Hub

State Hub is the live coordination service for the Custodian ecosystem: PostgreSQL persistence, FastAPI API, FastMCP server, Observable dashboard, consistency tooling, and repo/workplan synchronization.

This repository is the standalone home for the service. It replaces the former embedded implementation at:

/home/worsch/the-custodian/state-hub

Current Extraction State

The repo is being prepared by CUST-WP-0043 - State Hub Repo Extraction.

During extraction:

• The live implementation still exists in the-custodian/state-hub/.
• This repo owns the standalone baseline and will become authoritative after the implementation move and verification gate.
• State Hub implementation work should land here once registration and workplan re-homing are complete.

Stack

Layer	Technology	Default endpoint
Database	PostgreSQL	127.0.0.1:5432
API	FastAPI + SQLAlchemy async	127.0.0.1:8000
MCP	FastMCP SSE	127.0.0.1:8001/sse
Dashboard	Observable Framework	127.0.0.1:3000
CLI	custodian Python entry point	local shell

Expected Commands After Implementation Move

cp .env.example .env
make install
make db
make migrate
make seed
make api
make mcp-http
make dashboard
make test

Workplans

New State Hub-local workplans should use the prefix:

SHUB-WP-0001

Legacy Custodian-hosted State Hub plans, such as CUST-WP-0042, may be carried over with their existing State Hub IDs or bridged by a new SHUB-WP-* continuation plan. Do not create duplicate workstreams manually; write the workplan file first, then run consistency sync after this repo is registered.