e61c7ed15c
Service contract v0.1 accepted (Bernd 2026-07-10). Client-hub scoped as core-hub extension (client/engagement/app_instance/support_state, CLNT-WP skeleton). fin-hub gap assessment: 5 gaps, FIN-WP-0002 skeleton posted to fin-hub lane (msg 9c8e8ed4); recommendation fin-hub stays reporting-only. Remaining: T07 delivery-lane pilot, T08 closeout. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
83 lines
4.2 KiB
Markdown
83 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).
|