core-hub/.claude/rules/architecture.md

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