core-hub/docs/specs/core-hub-architecture.md

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.