## Architecture

Core Hub is contract-first. The stable framework surface is defined by specs, schemas, OpenAPI, event catalogs, manifests, fixtures, and compatibility tests before implementation details harden.

Initial component model:

- Contract/IR layer: documented schemas for hubs, capabilities, manifests, widgets, events, workplans, tasks, progress, messages, decisions, and registry facts.
- Service layer: Python/FastAPI application with Pydantic v2 DTOs, SQLAlchemy async models, Alembic migrations, asyncpg/Postgres persistence, and httpx integrations.
- Compatibility layer: Inter-Hub `/api/v2` endpoint preservation where ops-hub, activity-core, and existing consumers depend on it.
- UI layer: operator console and component surfaces aligned with whynot-design patterns; prefer framework-neutral contracts and Lit/custom-element adapters where useful.
- Migration layer: data import, row-count checks, fixture replay, dual-run smokes, and production cutover gates.

## Quick Reference

- `INTENT.md` - purpose and lineage
- `docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md` - research artifact
- `docs/specs/README.md` - spec map
- `workplans/` - ADR-001 workplans