aab187937b
Publish ecosystem architecture, event mapping, capability bridge, and async-base decision docs; add cross-repo regression script; update extraction boundary and bootstrap status; archive WP-0058 touch-ups.
105 lines
No EOL
4.8 KiB
Markdown
105 lines
No EOL
4.8 KiB
Markdown
# 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) |