konradcinkusz Shared services: one codebase, N independent instances
Read references/SHARED-SERVICE-REUSE.md before applying any of this.
That file is the standard; everything below it is a summary to help you decide
whether this skill applies and to check your work afterwards.
Reference-architecture principles: P2, P3, P7.
What this standard covers
- One codebase, N independent instances
- An artifact dependency, never a source dependency
- Publishing must not depend on deploying
- Each consumer names its own instance
- Database per instance, reconciled with P3
- What this does not excuse
Failure modes
| Symptom | Cause |
|---|---|
| Two consumers' users can authenticate against each other's system | A shared trust root: the same signing key was reused across instances, so the tokens are mutually valid. Independent instances means independent key material (§1) |
| A consumer is running software nobody can identify | The image reference is :latest. Two consumers that deployed a week apart are on different builds while their config claims otherwise (§2) |
| The shared service cannot ship a release | The publish job was gated on the service's own deployment secrets, so a maintainer without a hosted instance cannot publish for consumers who need one (§3) |
| An upgrade to one consumer takes another consumer down | The two are not independent instances at all — somewhere a runtime edge was introduced, usually a "temporary" pointer at the other's deployment (§1) |
| Nobody can tell whose instance an app is | Instances named after the shared service rather than the consumer, so ownership is not answerable from the platform itself (§4) |
| A consumer's incident review finds a defect the service already knew about | The extraction was treated as an audit. The defect travelled with the design and nobody wrote it down (§6) |
Checklist
- Every consumer runs its own compute, its own database and its own independently generated signing key; no key material is reused across instances
- Consumers reference a pinned image tag, never
:latest, and never take a source-level dependency (no submodule, no cross-repo project reference) - The publish workflow needs only a registry credential; the service's own deployment, if any, lives in separate jobs that cannot gate it
- A maintainer with no hosted instance of their own can still cut a release
- Instances are named for the consumer, not for the shared service
- Each instance's database is its own logical database with its own role and no cross-grants — co-location on an existing server is a cost decision, not a boundary change
- The extraction's deviation register records what came across unaudited from the source
Generated from docs/guides/SHARED-SERVICE-REUSE.md by scripts/build-marketplace.mjs. Do not edit this file: change the source document, or its entry in catalog/marketplace.catalog.json, and re-run the generator.