the-custodian/docs/business-platform-decision-records.md

Business Platform Decision Records

Created: 2026-07-10 Workplan: CUST-WP-0058 Status: All three decisions resolved by Bernd on 2026-07-10 (hub decision records d85cd185…, 1f8b109e…, ebcf0573…). See Resolutions and consistency refinement at the end; the option tables below are kept as decision history.

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: resolved 2026-07-10 — Option C (hybrid)

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: resolved 2026-07-10 — Option B (standalone application)

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: resolved 2026-07-10 — Option A (app-local accounts), demand-gated follow-up

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

---

Resolutions and consistency refinement (2026-07-10)

All three decisions were resolved by Bernd in the State Hub on 2026-07-10. The resolved set was then reviewed for internal consistency; two refinements follow from reading the three choices together.

Resolved set

DR	Choice	Bernd's rationale (hub record)
DR-1	C — hybrid	Instance-per-client to serve early customers easily, but "move on to resource cost optimization early"
DR-2	B — standalone app	coulomb.social is its own application, distinct in purpose and operations model; an application of Binky Hedgehog GmbH just as other apps are provided to clients; the fact that Binky Hedgehog provides the ecosystem (coulomb domain, Forgejo repos) is not relevant to the app itself
DR-3	A — app-local accounts	Lightweight version now; follow up with Keycloak (NK-WP-0011) only on actual demand

Unifying model

Binky Hedgehog GmbH is client #1 of its own platform. coulomb.social is delivered through the same standalone-app lane, service contract, and tenancy rules as apps sold to external clients. There is exactly one app shape (standalone service, forge→apps delivery) and one tenancy default (instance-per-client) — no special cases.

Refinement 1 — consolidation-readiness (DR-1 C ↔ DR-3 A)

DR-1's early cost-optimization move implies consolidating instances later, which app-local accounts per instance would turn into an account-migration problem. Therefore:

• The business-app service contract (CUST-WP-0058-T04) must require consolidation-ready design: tenant-clean data model (all client data keyed by a tenant identifier) even when deployed single-tenant.
• Instance consolidation is itself a DR-3 demand trigger: when the cost-optimization move consolidates instances, the platform-identity follow-up (NK-WP-0011) activates as part of that move.

Refinement 2 — identity triggers corrected (DR-2 B ↔ DR-3 A)

The original DR-3 framing made a coulomb.social greenlight an automatic Keycloak trigger. DR-2 B + DR-3 A overrule this: a standalone social app owning its own user accounts is a normal, viable shape. The corrected, purely demand-based triggers for activating NK-WP-0011 are:

1. A client requests SSO / AD federation.
2. Instance consolidation under DR-1's cost-optimization move (Refinement 1).
3. Operational toil from local account administration across >2 apps.

Downstream actions

• T04 service contract: encode instance-per-client provisioning, consolidation-ready data model, app-local identity baseline.
• T05 client-hub scoping: client↔instance mapping assumes 1..n instances per client, consolidation-aware.
• NetKingdom lane notified: NK-WP-0011 stays proposed with the three triggers above (no auto-activation).
• coulomb.social rebuild + bubble.io migration assessment: seeded as standalone-app workplan skeletons (T08), consuming the same delivery lane as vergabe-teilnahme.