---
title: Business-App Service Contract
version: v0.1
status: accepted
review: approved by Bernd 2026-07-10
created: "2026-07-10"
workplan: CUST-WP-0058
task: CUST-WP-0058-T04
decisions: [DR-1 (d85cd185), DR-2 (1f8b109e), DR-3 (ebcf0573)]
---

# Business-App Service Contract v0.1

Obligations every client-facing business application on the coulomb/HelixForge
platform must meet before serving a paying client. Applies **equally** to apps
sold to external clients and to Binky Hedgehog GmbH's own applications
(coulomb.social) — per DR-2, Binky Hedgehog is client #1 of its own platform.
There is one app shape and one contract; no special cases.

**Reference implementation:** `vergabe-teilnahme` (first app through the
delivery-lane pilot, `CUST-WP-0058-T07`).

## 1. Shape and tenancy (DR-1 C, DR-2 B)

- **1.1** A business app is a **standalone service**: own repo, own database,
  own release values. It is not a Core Hub extension.
- **1.2** Default deployment is **instance-per-client**: dedicated deployment
  and database per client, own entry in `railiance-apps` release values.
- **1.3** **Consolidation-ready data model** (mandatory): all client-owned
  data is keyed by a tenant identifier from the first migration onward, even
  though each instance serves exactly one tenant. Rationale: DR-1's early
  cost-optimization move may consolidate instances; a tenant-clean schema
  makes that a data-copy, not a rewrite.
- **1.4** No app may hard-code the assumption "I am the only tenant" in
  business logic, exports, or backup formats.

## 2. Identity (DR-3 A)

- **2.1** v1 baseline is **app-local accounts**, scoped to the instance.
- **2.2** Account data lives in the instance database and is covered by the
  same tenant keying as §1.3 (consolidation moves accounts with the tenant).
- **2.3** Apps must isolate authentication behind a single module/boundary so
  a later switch to platform OIDC (NK-WP-0011 Keycloak) is a bounded change.
- **2.4** Platform identity activates only on the recorded demand triggers
  (client SSO/AD request; instance consolidation; local-account toil across
  >2 apps) — see `docs/business-platform-decision-records.md`.

## 3. Build and release evidence

- **3.1** Images are built from the app repo and tagged with the **immutable
  commit SHA**; `latest` must never be the only production reference.
- **3.2** Images are published to `gitea.coulomb.social/coulomb/<app>`.
- **3.3** Release values live in `railiance-apps`; the app repo owns build
  scripts and image metadata (railiance-forge pattern).
- **3.4** Each client-visible release records: source repo, commit SHA,
  image tag/digest, smoke result, and the release-values change. Evidence
  reports contain **no secrets** (SOPS/OpenBao references only).

## 4. Operations (ops-hub)

- **4.1** Every client instance is registered in ops-hub: service, endpoint,
  environment, and owning client.
- **4.2** **Backup/restore**: each instance database has a scheduled backup
  and a tested restore path; evidence of the last successful restore test is
  recorded before the first paying client and after schema-major changes.
- **4.3** Incidents affecting a client instance are recorded against that
  instance; every app ships at least a minimal runbook (start/stop, backup,
  restore, upgrade, known failure modes).
- **4.4** A deployed smoke check exists and runs after every release.

## 5. Cost and billing (fin-hub)

- **5.1** Every instance carries a **cost attribution key**
  (`client × app × instance`) usable by fin-hub cost ingestion.
- **5.2** Infrastructure cost per instance must be reportable — this feeds
  DR-1's cost-optimization decision point.
- **5.3** Price-to-invoice flow is out of scope for the app itself; the app
  only guarantees the attribution key exists (fin-hub gap: CUST-WP-0058-T06).

## 6. Data protection

- **6.1** Client data is processed within the platform's infrastructure;
  per-instance isolation (§1.2) is the v1 isolation guarantee stated to
  clients.
- **6.2** Apps must support export and deletion of a client's complete data
  set (offboarding = export + instance teardown + backup expiry).
- **6.3** Personal data inventories and AV/DPA contract mechanics are a
  Binky Hedgehog GmbH obligation, tracked outside this standard; the app
  must be able to answer "what personal data do you store" from its schema.
- **6.4** No plaintext credentials in repos, images, logs, or evidence
  (existing credential-routing canon applies).

## 7. Client plane integration (forward-looking)

- **7.1** Once client-hub exists (scoping: CUST-WP-0058-T05), each instance
  registers its client↔instance mapping there; until then the mapping lives
  in ops-hub instance metadata (§4.1).
- **7.2** Contract/entitlement state is never encoded in the app itself.

## 8. Conformance

- **8.1** A new app (or new client instance) is conformant when §1–§6 are
  satisfied and evidenced; §7 applies once client-hub is live.
- **8.2** The delivery-lane pilot (CUST-WP-0058-T07) validates this contract
  end-to-end with vergabe-teilnahme; findings feed v0.2.
- **8.3** Deviations require a recorded State Hub decision, not silent
  exceptions.