# Hub Ecosystem Architecture

**Updated:** 2026-07-09  
**Workplan:** `CUST-WP-0057`  
**Status:** Active decision record

---

## Purpose

Define how `hub-core`, `state-hub`, and `core-hub` compose into one FOS hub
stack. This document resolves naming confusion and entity ownership without
merging repositories.

---

## Three-layer model

| Layer | Repo | Role | Production URL |
| --- | --- | --- | --- |
| **Library** | `hub-core` | Shared models, schemas, router factories, MCP wrapper, utils | None — pip/uv import only |
| **Dev coordination** | `state-hub` | File-first workplans, tasks, decisions, consistency sync, dev MCP | Local / operator (`127.0.0.1:8000`) |
| **Production framework** | `core-hub` | Inter-Hub successor: hubs, manifests, widgets, `/api/v2`, operator console | `hub.coulomb.social` |

```text
                    ┌─────────────────┐
                    │    core-hub     │  Production framework (/api/v2)
                    │  (async service)│
                    └────────┬────────┘
                             │ imports utils; HTTP bridge to dev data (future)
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
       ┌────────────┐  ┌────────────┐  ┌────────────┐
       │  hub-core  │◄─│ state-hub  │  │  ops-hub   │
       │  (library) │  │ (dev host) │  │ (consumer) │
       └────────────┘  └────────────┘  └────────────┘
```

---

## Naming glossary

| Name | What it is | What it is not |
| --- | --- | --- |
| **hub-core** | Python package `hub_core` — library boundary | A running hub service |
| **core-hub** | Production interaction framework service | The shared library |
| **state-hub** | Dev coordination host (State Hub / dev-hub) | The Inter-Hub `/api/v2` framework |

Mnemonic: **hub-core** = core *primitives*; **core-hub** = core *framework runtime*.

---

## Canonical entity ownership

| Entity family | Canonical owner | Notes |
| --- | --- | --- |
| `domains`, `managed_repos` (registry) | `hub-core` models; `state-hub` host | core-hub uses `hubs` table — see capability bridge doc |
| `agent_messages` | `hub-core` + `state-hub` | core-hub does not duplicate; reads via State Hub API when needed |
| `progress_events` | `hub-core` + `state-hub` | Dev coordination audit trail |
| `interaction_events` | `core-hub` | Widget-scoped ops evidence (`/api/v2/interaction-events`) |
| `capability_catalog`, `capability_requests` | `hub-core` + `state-hub` | Maturity and workflow lane |
| `hub_capability_manifests` | `core-hub` | Inter-Hub manifest contract |
| `hubs`, `widgets`, `api_consumers`, `api_keys` | `core-hub` | Framework registry only |
| `workplans`, `tasks`, `decisions` | `state-hub` | File-first authority; core-hub may index later |
| `tpsc_*`, policy documents | `hub-core` + `state-hub` | core-hub references evidence, does not reimplement |
| Slug/pagination/path utils | `hub-core` | All hosts import; no local duplicates |

---

## Governing decisions

1. **Compose, do not merge** — three repos remain; shared code moves into `hub-core`.
2. **hub-core stays a library** — no `uvicorn` entrypoint, no K8s manifests.
3. **core-hub owns `/api/v2`** — Inter-Hub compatibility is non-negotiable for ops-hub and activity-core.
4. **state-hub owns dev coordination** — workplan files remain source of truth until a recorded ADR says otherwise.
5. **Separate SQLAlchemy metadata** — each runtime keeps its own `Base`; router factories inject host models.
6. **Incremental adoption** — core-hub adopts hub-core utilities first; framework models stay local.

---

## Integration contracts

| From | To | Mechanism | Status |
| --- | --- | --- | --- |
| `state-hub` | `hub-core` | Editable package import | Done (`CUST-WP-0048`) |
| `core-hub` | `hub-core` | Editable package import (utils) | In progress (`CORE-WP-0009`) |
| `core-hub` | `state-hub` | HTTP read APIs for progress/messages | Deferred (`STATE-WP-0070`) |
| `ops-hub` | `core-hub` | `/api/v2` bootstrap | Production |
| Agents | `state-hub` | dev-hub MCP | Production |
| Operators | `core-hub` | Operator CLI + console | Production |

See also:

- `hub-ecosystem-event-mapping.md` — progress vs interaction events
- `hub-ecosystem-capability-bridge.md` — catalog vs manifest IDs
- `hub-core-extraction-boundary.md` — library extraction history

---

## Non-goals

- Renaming `hub-core` or `core-hub` repositories
- Moving State Hub workplan tables into core-hub in this lane
- Replacing core-hub `/api/v2` with state-hub routes
- Publishing hub-core to public PyPI (path/editable deps remain fine)