84 lines
4.2 KiB
Markdown
84 lines
4.2 KiB
Markdown
|
# Client-Hub Scoping — the Client/Commercial Management Plane
|
|||
|
|
|
|||
|
|
**Created:** 2026-07-10
|
|||
|
|
**Workplan:** `CUST-WP-0058-T05`
|
|||
|
|
**Decisions applied:** DR-1 C (instance-per-client, consolidation-aware),
|
|||
|
|
DR-2 B (Binky Hedgehog GmbH as client #1), DR-3 A (app-local identity)
|
|||
|
|
**Contract:** `canon/standards/business-app-service-contract_v0.1.md` (§7)
|
|||
|
|
|
|||
|
|
## Why a fourth plane
|
|||
|
|
|
|||
|
|
The hub ecosystem manages dev (state-hub), ops (ops-hub), and fin (fin-hub)
|
|||
|
|
concerns. Commercial operation of business apps adds concerns none of those
|
|||
|
|
own: who the clients are, what they are entitled to, which instances serve
|
|||
|
|
them, and what support/SLA state applies. Encoding any of this in the apps
|
|||
|
|
themselves is prohibited by the service contract (§7.2).
|
|||
|
|
|
|||
|
|
## Shape decision: core-hub extension
|
|||
|
|
|
|||
|
|
**Client-hub is a Core Hub extension (ops-hub pattern), not a standalone
|
|||
|
|
runtime.** Justification against the alternatives:
|
|||
|
|
|
|||
|
|
- *Standalone service*: adds an operational surface (deploy, backup, monitor)
|
|||
|
|
for what is initially a small registry; contradicts the "don't spawn a
|
|||
|
|
runtime per aspect" guard from the hub-ecosystem review.
|
|||
|
|
- *fin-hub extension*: client identity is not a financial concern; billing
|
|||
|
|
*references* clients but does not own them.
|
|||
|
|
- *state-hub tables*: state-hub is the internal dev plane and must stay out
|
|||
|
|
of anything client-related (dev plane never in the client dependency graph).
|
|||
|
|
|
|||
|
|
Core Hub is the production framework (`hub.coulomb.social`), already runs the
|
|||
|
|
ops-hub extension, and hub-core primitives (domains/repos/messages/progress
|
|||
|
|
router factories, JSON context seams) are available for reuse where they fit.
|
|||
|
|
|
|||
|
|
## Entity model (v1)
|
|||
|
|
|
|||
|
|
| Entity | Purpose | Key fields (sketch) |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| `client` | Business client registry; **Binky Hedgehog GmbH is client #1** | name, legal form, contacts, status (prospect/active/offboarding/closed) |
|
|||
|
|
| `engagement` | Contract/entitlement envelope per client×app | client_id, app slug, entitlements (JSON), contract refs (pointer, no documents), start/end |
|
|||
|
|
| `app_instance` | Client↔instance mapping (1..n per client, DR-1) | client_id, engagement_id, app slug, environment ref (ops-hub), cost attribution key (fin-hub §5.1), consolidation state (dedicated/consolidated) |
|
|||
|
|
| `support_state` | SLA/support posture per engagement | tier, contacts, escalation path, open-issue pointer (issue-core) |
|
|||
|
|
|
|||
|
|
Relations to other planes are **references, not ownership**: `app_instance`
|
|||
|
|
points at ops-hub environment/service records and carries the fin-hub cost
|
|||
|
|
key; documents/contracts stay in their own custody (no file storage here).
|
|||
|
|
|
|||
|
|
## Boundaries (out of scope)
|
|||
|
|
|
|||
|
|
- Payment, invoicing, dunning — fin-hub boundary question (T06)
|
|||
|
|
- Contract document storage or legal authority — human/Binky Hedgehog custody
|
|||
|
|
- Client *user* accounts — app-local per DR-3; client-hub tracks the client
|
|||
|
|
organization, never its end users
|
|||
|
|
- Task/issue lifecycle — issue-core owns; support_state only points
|
|||
|
|
|
|||
|
|
## Consolidation-awareness (DR-1 C)
|
|||
|
|
|
|||
|
|
`app_instance.consolidation_state` plus the tenant key make the early
|
|||
|
|
cost-optimization move a data operation: consolidating N instances updates N
|
|||
|
|
rows (dedicated→consolidated onto shared infra) without model changes.
|
|||
|
|
Consolidation events must emit a signal that the DR-3 identity trigger can
|
|||
|
|
observe.
|
|||
|
|
|
|||
|
|
## Proposed workplan skeleton (for `/home/worsch/core-hub` or a `client-hub` extension repo)
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
CLNT-WP-0001 — client-hub extension bootstrap
|
|||
|
|
T01 Extension scaffold following ops-hub repo pattern (todo, high)
|
|||
|
|
T02 client + engagement models, migrations, /api/v2 routes (todo, high)
|
|||
|
|
T03 app_instance model with ops-hub env ref + fin-hub cost key (todo, high)
|
|||
|
|
T04 support_state model + issue-core pointer (todo, medium)
|
|||
|
|
T05 Seed client #1 (Binky Hedgehog GmbH) + vergabe-teilnahme pilot
|
|||
|
|
engagement/instance rows (todo, medium)
|
|||
|
|
T06 Operator console views (clients, engagements, instances) (todo, low)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Ownership question for Bernd at pickup: separate `client-hub` repo (like
|
|||
|
|
`ops-hub`) or a module inside `core-hub`? Recommendation: **separate repo**,
|
|||
|
|
consistent with the established extension pattern and repo-boundary rules.
|
|||
|
|
|
|||
|
|
## Pickup
|
|||
|
|
|
|||
|
|
Registered as an ecosystem todo when CUST-WP-0058-T08 closes; implementation
|
|||
|
|
does not start inside the-custodian (repo-boundary).
|