generated from coulomb/repo-seed
42 lines
3.6 KiB
Markdown
42 lines
3.6 KiB
Markdown
# INTENT - Core Hub
|
|
|
|
## Purpose
|
|
|
|
Core Hub is the 3rd-generation Production Interaction Framework for Coulomb / Helixforge.
|
|
|
|
It rebuilds the goals of the 2nd-generation Inter-Hub idea on a practical production stack: contract-first, Python/FastAPI/Postgres at the service layer, explicit compatibility tests, and UI patterns that can flow from the whynot-design process without binding the system to one framework or one agent runtime.
|
|
|
|
## Lineage
|
|
|
|
- Generation 1: `state-hub` proved file-backed workplans, State Hub read models, progress events, messages, tasks, and agent coordination.
|
|
- Generation 2: `inter-hub` introduced the broader hub framework idea: separate domain hubs, shared manifests, widgets, registries, events, and a unified operator surface. The idea was right, but the Haskell/IHP/Nix path was too heavy for the available infrastructure.
|
|
- Generation 3: `core-hub` keeps the Inter-Hub ambition but makes it operationally ordinary: simple local development, fast tests, visible contracts, migration discipline, and deployment through the existing Railiance platform rather than a bespoke Haskell build lane.
|
|
|
|
## Product Intent
|
|
|
|
Core Hub should become the production interaction substrate where domains publish state, capabilities, evidence, decisions, workplans, agent messages, registry facts, and operator UI components through one coherent framework.
|
|
|
|
The framework must be usable by humans and agents. Human operators need a stable console and clear audit trail. Agents need typed APIs, predictable workflows, and durable contract documentation. Downstream hubs need a way to integrate without inheriting Core Hub internals.
|
|
|
|
## Core Principles
|
|
|
|
1. Contract first: schemas, OpenAPI, event catalogs, capability manifests, and compatibility tests precede implementation convenience.
|
|
2. Adapter friendly: the core model is independent from any one UI or service framework. Implementations consume the contract, they do not become the contract.
|
|
3. Operationally light: local setup, tests, and deployment must fit the natural Coulomb stack and avoid special-purpose Haskell/Nix build paths.
|
|
4. Migration honest: Core Hub preserves the useful Inter-Hub semantics while making incompatibilities explicit and testable.
|
|
5. Credential-safe: no secrets in Git, State Hub, workplans, logs, or chat. Credential ownership follows the ops-warden/OpenBao/key-cape routing model.
|
|
6. Agent-native: workplans remain file-first, State Hub remains a read/cache/index layer until Core Hub intentionally replaces or absorbs that role.
|
|
7. Self-optimizing: regular reviews identify recurring error states, necessary workarounds, needless complexity from unnecessary information passing, and other inefficiencies so the framework can simplify its own operating patterns over time.
|
|
|
|
## Initial Platform Direction
|
|
|
|
- Backend: Python 3.12, FastAPI, Pydantic v2, SQLAlchemy async, Alembic, asyncpg/Postgres, httpx.
|
|
- Contracts: OpenAPI, JSON Schema, SQL/Alembic migrations, registry YAML/Markdown where appropriate.
|
|
- Tests: pytest, contract fixtures, API compatibility tests, migration checks.
|
|
- UI: whynot-design aligned tokens and Lit/custom-element adapters where UI components are needed; avoid locking the framework to React.
|
|
- Deployment: Docker/Kubernetes/ArgoCD/Gitea or Forgejo workflows on the normal platform path; no GHC/IHP/Nix build dependency for the new framework.
|
|
|
|
## Current State
|
|
|
|
This repo has been re-bound from the `repo-seed` template into the Core Hub planning and specification home. The first implementation work is organized around contract extraction, FastAPI/Postgres foundation, Inter-Hub compatibility, data migration, operator UI, and retirement of the Haskell build lane after cutover.
|