diff --git a/docs/business-platform-decision-records.md b/docs/business-platform-decision-records.md new file mode 100644 index 0000000..07655aa --- /dev/null +++ b/docs/business-platform-decision-records.md @@ -0,0 +1,140 @@ +# Business Platform Decision Records + +**Created:** 2026-07-10 +**Workplan:** `CUST-WP-0058` +**Status:** All three decisions **pending** — Bernd's to resolve; this document +frames options and recommendations only. + +## Context + +Binky Hedgehog GmbH intends to build commercial business applications on the +coulomb/HelixForge platform (Forgejo → railiance-forge → railiance-apps → +Core Hub ecosystem): + +1. **vergabe-teilnahme** — tender-participation web app as the first + commercial offering for business clients. +2. **coulomb.social rebuild** — replace the current bubble.io implementation + as the second business project. + +The hub-ecosystem review (2026-07-09, see `hub-ecosystem-architecture.md`) +concluded the architecture is sound but three decisions gate the business +lane. Each is recorded here with options and a recommendation; resolution +happens via State Hub decision records (`resolve_decision`). + +--- + +## DR-1 — Tenancy model for vergabe-teilnahme + +**Status:** pending + +### Question + +How are business clients isolated: one deployed instance per client, or one +multi-tenant instance? + +### Options + +| Option | Description | Consequences | +| --- | --- | --- | +| **A. Instance-per-client** | Each client gets a dedicated deployment (own DB, own release values in `railiance-apps`) | Strong isolation; simpler compliance story; per-client backup/restore; matches vergabe-teilnahme SCOPE ("no multi-tenancy"); ops-hub must model *client instances*; fin-hub needs per-instance cost attribution; N instances = N upgrade operations | +| **B. Multi-tenant single instance** | One deployment, tenant column / row-level isolation | Cheaper to operate at scale; contradicts current SCOPE; requires tenancy rework in the app; single blast radius for incidents and data-protection failures | +| **C. Hybrid (A now, B later)** | Start instance-per-client; revisit at a client-count threshold | Defers rework until demand proves it; risk of never consolidating | + +### Recommendation + +**Option A (instance-per-client) for v1**, with an explicit revisit trigger +(e.g. >5 paying clients or upgrade toil exceeding one operator-day/month). +It matches the app's current SCOPE, the railiance-apps per-app values +pattern, and gives the cleanest early compliance/data-protection story for +German business clients. + +### Downstream effects once resolved + +- ops-hub: add client-instance entity (environment × client mapping) +- fin-hub: per-instance cost attribution keys +- Business-app service contract (CUST-WP-0058-T04): codify instance + provisioning/backup/upgrade obligations + +--- + +## DR-2 — coulomb.social rebuild architecture + +**Status:** pending + +### Question + +Is the coulomb.social rebuild a **Core Hub extension** (hubs/widgets/ +manifests, ops-hub pattern) or a **standalone application** (vergabe- +teilnahme pattern)? + +### Options + +| Option | Description | Consequences | +| --- | --- | --- | +| **A. Core Hub extension** | Built on `/api/v2` framework: hubs, widgets, manifests, interaction events | Reuses production framework already at `hub.coulomb.social`; interaction-platform semantics fit; couples product evolution to core-hub framework maturity; framework gaps become product blockers | +| **B. Standalone app** | Own service repo, own DB, deployed via forge→apps lane like vergabe-teilnahme | Full product freedom; no framework coupling; duplicates interaction/identity plumbing core-hub already has; two social-ish surfaces to keep coherent | +| **C. Defer until after the vergabe-teilnahme pilot** | Run the delivery-lane pilot first; decide with evidence | Costs calendar time; decision made with real platform evidence instead of speculation | + +### Recommendation + +**Option C, with a leaning toward A.** The delivery-lane pilot +(CUST-WP-0058-T07) will expose whether the forge→apps path and Core Hub +framework are mature enough to host a client-facing interaction product. +Deciding now would be speculation; the bubble.io exit additionally needs a +separately-scoped **data migration** assessment regardless of which shape +wins. + +### Downstream effects once resolved + +- A → core-hub gains its first external-product extension; widget/manifest + contract hardening becomes product-critical +- B → second entry in the business-app service contract; shared identity + becomes the only coupling point +- Either → bubble.io data-export/migration workplan in the owning repo + +--- + +## DR-3 — External identity path for business clients + +**Status:** pending + +### Question + +What identity stack serves *external* users (client employees, later +coulomb.social members): the current lightweight internal stack +(KeyCape/Authelia/LLDAP) or the proposed expanded-mode Keycloak lane +(`NK-WP-0011`)? + +### Options + +| Option | Description | Consequences | +| --- | --- | --- | +| **A. Lightweight stack, app-local accounts for v1** | vergabe-teilnahme manages its own user accounts per instance; platform identity stays internal | Fastest to ship; consistent with instance-per-client isolation; no SSO story; identity debt accrues per app | +| **B. Activate NK-WP-0011 (Keycloak expanded mode) now** | Platform-level OIDC for external users before first client onboarding | One identity story from day one; enterprise federation ready; heavyweight — delays first client; NK-WP-0011 is only *proposed* | +| **C. Trigger-based: A for vergabe-teilnahme v1, B gated on defined triggers** | Define explicit conditions that activate the Keycloak lane (e.g. coulomb.social greenlight, first client requesting SSO/AD federation, >2 apps with local accounts) | Ships v1 fast without pretending identity debt doesn't exist; triggers make the debt visible and bounded | + +### Recommendation + +**Option C.** Vergabe-teilnahme v1 explicitly excludes external partner +accounts and is instance-per-client, so app-local auth is defensible *for +that app*. coulomb.social is the forcing function: any resolution of DR-2 +that greenlights the rebuild should automatically activate the NK-WP-0011 +lane, because a social platform on app-local accounts is not viable. + +### Downstream effects once resolved + +- NetKingdom: NK-WP-0011 gets concrete activation triggers instead of + indefinite "proposed" status +- Business-app service contract: identity section states which mode each + app class must use + +--- + +## Resolution protocol + +1. Each DR is registered as a pending State Hub decision (custodian topic). +2. Bernd resolves via `resolve_decision()` or by stating the choice in a + session; the resolving agent updates this document's status lines and the + hub record together. +3. `CUST-WP-0058` tasks T01–T03 track the facilitation; downstream tasks + stay `wait` until their gating DR is resolved. diff --git a/workplans/CUST-WP-0058-business-platform-enablement.md b/workplans/CUST-WP-0058-business-platform-enablement.md new file mode 100644 index 0000000..328599e --- /dev/null +++ b/workplans/CUST-WP-0058-business-platform-enablement.md @@ -0,0 +1,184 @@ +--- +id: CUST-WP-0058 +type: workplan +title: "Business platform enablement — decisions, service contract, client plane" +domain: infotech +repo: the-custodian +status: proposed +owner: codex +topic_slug: custodian +created: "2026-07-10" +updated: "2026-07-10" +--- + +# CUST-WP-0058 — Business Platform Enablement + +## Goal + +Enable Binky Hedgehog GmbH commercial offerings on the coulomb/HelixForge +platform by (a) resolving the three gating platform decisions, (b) codifying +what every client-facing business application must provide, and (c) scoping +the missing client/commercial management plane — so that **vergabe-teilnahme** +(first business project) and the **coulomb.social rebuild** (second) land on +a governed, extensible path rather than ad hoc wiring. + +This is a *coordination* workplan: implementation lands in the owning repos +(`vergabe-teilnahme`, `fin-hub`, `ops-hub`, `core-hub`, railiance repos). +The Custodian owns decisions, canon, and cross-repo sequencing per ADR-001. + +## Background + +- Hub-ecosystem review 2026-07-09: architecture sound (hub-core / state-hub / + core-hub compose-don't-merge, `CUST-WP-0057`); gaps are a missing + client/commercial plane and three unrecorded decisions. +- Decision framing: `docs/business-platform-decision-records.md` (DR-1 + tenancy, DR-2 coulomb.social shape, DR-3 external identity). +- fin-hub MVP (cost tracking, runway, RaaS pricing MVP) shipped via + `FIN-WP-0000/0001`; **client-facing billing** remains open. +- Delivery lane pattern proven for Core Hub + (`docs/core-hub-helixforge-build-alignment.md`): commit-SHA images → + `gitea.coulomb.social` registry → railiance-apps release values → + evidence gates. + +## Non-goals + +- Implementing vergabe-teilnahme features (owned by that repo) +- Rebuilding coulomb.social (blocked on DR-2; owned by its future repo) +- Building client-hub (this plan only *scopes* it; implementation gets its + own workplan in the owning repo) +- Payment execution / invoicing mechanics (fin-hub scope decision) + +## Tasks + +### T01 — Facilitate and record DR-1: tenancy model + +```task +id: CUST-WP-0058-T01 +status: todo +priority: high +``` + +Register DR-1 as a pending State Hub decision (custodian topic); present +options to Bernd; on resolution update +`docs/business-platform-decision-records.md` and `resolve_decision()`. +Propagate the outcome into vergabe-teilnahme's SCOPE if it changes. + +### T02 — Facilitate and record DR-2: coulomb.social architecture + +```task +id: CUST-WP-0058-T02 +status: todo +priority: medium +``` + +Register DR-2 as a pending State Hub decision. If resolution is +"defer until pilot" (recommended), set the revisit condition to T07 +completion and keep the decision open with that note. Include a pointer to +the required bubble.io data-migration assessment either way. + +### T03 — Facilitate and record DR-3: external identity path + +```task +id: CUST-WP-0058-T03 +status: todo +priority: high +``` + +Register DR-3 as a pending State Hub decision. On resolution, message the +NetKingdom lane so `NK-WP-0011` gains concrete activation triggers (or is +activated). Record the identity mode required per app class for T04. + +### T04 — Author business-app service contract (canon standard) + +```task +id: CUST-WP-0058-T04 +status: wait +priority: high +``` + +Draft `canon/standards/business-app-service-contract_v0.1.md` (proposal → +human review, per canon gating): obligations every client-facing app must +meet — build evidence (commit-SHA images, registry), backup/restore hooks +into ops-hub, incident/runbook registration, cost attribution keys for +fin-hub, identity mode (from DR-3), data-protection baseline, and instance +provisioning/upgrade duties (from DR-1). vergabe-teilnahme is the reference +implementation. **Waits on:** DR-1 and DR-3 resolution (T01, T03). + +### T05 — Scope client-hub (client/commercial plane) + +```task +id: CUST-WP-0058-T05 +status: wait +priority: medium +``` + +Write a scoping note (`docs/client-hub-scoping.md`) for the missing fourth +management plane: client registry, contracts/entitlements, client↔instance +mapping, support/SLA state. Default shape: **core-hub extension** (ops-hub +pattern) reusing hub-core primitives — justify any deviation. Output is a +draft workplan skeleton for the owning repo, not implementation. +**Waits on:** DR-1 resolution (T01) — tenancy determines the +client↔instance model. + +### T06 — fin-hub client-billing gap assessment + +```task +id: CUST-WP-0058-T06 +status: todo +priority: medium +``` + +Review `FIN-WP-0000/0001` outcomes against what commercial clients need: +per-client cost attribution, price-to-invoice data flow, and where the +fin-hub "no payment execution / no multi-tenant billing" boundary should +move (or which external system owns billing). Output: gap list + proposed +FIN-WP workplan skeleton posted to the fin-hub lane. + +### T07 — Delivery-lane pilot: vergabe-teilnahme end-to-end + +```task +id: CUST-WP-0058-T07 +status: wait +priority: high +``` + +Coordinate one full pass of the business delivery lane with a real (or +pilot) client instance: vergabe-teilnahme build → immutable image in +`gitea.coulomb.social` registry → railiance-apps release values → deployed +instance → ops-hub evidence (endpoint, backup, smoke) → fin-hub cost +attribution. Implementation tasks live in the owning repos; this task tracks +sequencing and captures the evidence bundle under `docs/evidence/`. +Feeds DR-2 resolution. **Waits on:** T01 (tenancy) and T04 (contract +draft — may proceed in parallel once DR-1 is resolved). + +### T08 — Closeout: decisions recorded, downstream workplans seeded + +```task +id: CUST-WP-0058-T08 +status: wait +priority: low +``` + +Verify all three DRs resolved (or explicitly deferred with revisit +conditions), the service contract standard is merged in canon, and +downstream workplan skeletons (client-hub, fin-hub billing, coulomb.social +rebuild + bubble.io migration) are handed to their owning repos. Update +SCOPE.md Current State; archive this plan. + +## Sequencing + +```text +T01 (DR-1) ──┬──> T04 (contract) ──> T07 (pilot) ──> DR-2 evidence ──> T02 closes + └──> T05 (client-hub scope) +T03 (DR-3) ──┘ +T06 (fin-hub gap) — independent, anytime +T08 — last +``` + +## References + +- `docs/business-platform-decision-records.md` — DR-1/2/3 framing +- `docs/hub-ecosystem-architecture.md` — three-layer hub canon +- `docs/core-hub-helixforge-build-alignment.md` — delivery lane pattern +- `/home/worsch/vergabe-teilnahme/SCOPE.md` — first business app +- `/home/worsch/fin-hub/workplans/` — FIN-WP-0000/0001 (finished)