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.