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>
107 lines
5.1 KiB
Markdown
107 lines
5.1 KiB
Markdown
---
|
||
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.
|