# Core Hub Architecture Spec

## Goal

Build the production interaction framework as a small set of explicit layers rather than a monolith.

## Layers

1. Contract/IR layer
   - OpenAPI
   - JSON Schema
   - Alembic/SQL schema
   - event, widget, and capability catalogs
   - fixtures and compatibility examples

2. Runtime service layer
   - FastAPI app
   - Pydantic v2 request/response DTOs
   - SQLAlchemy async persistence
   - Alembic migrations
   - asyncpg/Postgres
   - httpx clients for integration probes

3. Compatibility layer
   - Inter-Hub `/api/v2` routes required by current consumers
   - auth/error compatibility
   - response-shape fixtures
   - smoke scripts for ops-hub and activity-core

4. Operator UI layer
   - dashboard/console surfaces
   - whynot-design aligned tokens/components
   - adapter-friendly component model

5. Migration and operations layer
   - import/export tools
   - row-count and referential checks
   - dual-run smokes
   - release/cutover runbook

## Boundary Decisions

- Core Hub owns the framework contract and primary implementation.
- Domain hubs own their domain data and domain-specific runtime logic.
- Credential systems keep owning secrets; Core Hub records non-secret evidence and routing metadata only.
- State Hub remains active until Core Hub has a proven compatibility and migration path.