# Prompt & Configuration Registry

**Solution Architecture v1.0 · open source, self-hosted on Kubernetes · Platform Architecture · 2026-09 · 21 views · 17 architecture decision records**

The release control plane for the words, models and policies that decide what an AI feature says. Every company that has shipped an AI feature has discovered the same thing: the prompt is the product, and the prompt is not in a release. A support assistant answering millions of conversations is governed by a system prompt, a model choice, a tool list, a temperature and a refusal policy — all of which need to change faster than the service reading them ships, and all of which are usually a YAML file that is too slow, a database row edited by hand with no history, or a feature-flag product bent into a shape it was not built for. This one carries 2,000 configuration keys and 25,000 published versions across roughly 300 consuming deployments, resolving 40,000 times a second, on Forgejo and an OCI registry for artefacts, etcd for pointers, NATS JetStream for propagation, PostgreSQL for authoring, ClickHouse for exposures, OpenBao for signing and SPIRE for workload identity.

The design rests on one boundary: **the authoring plane and the resolution plane share nothing but an immutable signed bundle and a pointer to it.** Authoring is transactional, human-paced and allowed to be unavailable. Resolution lives inside ~300 application processes, holds one verified bundle in memory, and needs nothing from the control plane to keep answering. That single seam is what makes a 3 ms p99 achievable, what licenses a lower availability target for the registry than for the features it governs, what makes reproducibility structural rather than aspirational, and what turns rollback into a pointer write against an artefact that already exists.

The decisions that carry the design:

- **The resolution plane never reads the authoring store.** A control-plane outage means "no new releases", not "no AI features", and the latency budget is a property of a library rather than of the slowest managed service (ADR-01).
- **Resolution is a library, not a sidecar or a service.** Sub-millisecond answers and resolution context that never leaves the caller, at the cost of three implementations and an upgrade cadence set by the slowest consuming team (ADR-02).
- **Availability failures fail static; integrity failures fail closed.** Staleness is acceptable, unverified content is not — and classifying by what the failure tells you about the data in hand is what makes both outcomes right (ADR-03).
- **Rollback is promotion run backwards, with no approval gate.** One mechanism exercised daily beats an emergency path exercised once under pressure, and the target already passed every gate (ADR-04).
- **The poll guarantees convergence; the notice only makes it fast.** Losing the bus costs propagation latency and never correctness, which is what allows the bus to be ordinary infrastructure (ADR-05).
- **A version's identity is its content digest.** Reproducibility is a consequence of content addressing, not a feature added later: recovery at seven years is a lookup rather than a reconstruction (ADR-06).
- **The distributed unit is a whole-environment bundle with a 2 MB ceiling enforced at build.** Atomic multi-key change, one verification per artefact, and a failure mode that is a red build rather than a slow fleet (ADR-07).
- **All validation happens at build time; the resolver validates nothing but the signature.** A resolver able to reject a bundle for being malformed is a resolver able to fail a request (ADR-08).
- **Variant assignment is a pure function of unit and salt.** No store on the request path, no drift, and an analyst can recompute exactly what the resolver decided (ADR-09).
- **The registry owns experiment assignment for now, with the hand-over trigger stated.** Prompt experiments that must be mutually exclusive with pricing and interface experiments belong to the experimentation platform, and that condition is written down rather than discovered (ADR-10).
- **Authoring, approval and promotion are three separate grants.** Otherwise the audit trail records one person agreeing with themselves (ADR-11).
- **Bundles are signed with a sign-only role, and trust distribution leads key rotation.** A compromised build can sign during the compromise but cannot steal the ability to sign (ADR-12).
- **Model aliases are resolved and pinned at build time**, so a provider repointing a name is a visible diff instead of a silent change that invalidates every past digest (ADR-13).
- **Reproducibility retains the digest, not the rendered prompt.** The claim is behavioural equivalence, and the privacy obligation that byte-exactness would carry is named rather than absorbed (ADR-14).
- **A guardrail breach pages a human; it does not roll back.** The signals that matter for AI behaviour lag minutes to hours and are noisy, and a good change reverted for a reason nobody can explain is the more corrosive failure (ADR-15).
- **Exposure telemetry is droppable and declares its loss; the audit ledger is neither.** Two kinds of evidence, two durabilities, two pipelines (ADR-16).
- **One writable site; the secondary carries artefacts and cannot promote.** A site loss freezes the fleet on correct configuration rather than risking two sites disagreeing about which digest is current (ADR-17).

The architecture one-pager (including why the design should still hold up in ten years) and the full decision record appear on the landing page of the diagram set, directly below the index of views. The same content is published as [docs/architecture-one-pager.md](docs/architecture-one-pager.md) (~14 min) and [docs/decision-record.md](docs/decision-record.md) (~66 min).

---

## What is here

| Path | Contents |
|---|---|
| `diagrams/index.html` | The landing page: 21 views in seven acts with every format linked, then the **architecture one-pager** and the **decision record** |
| `diagrams/*.html` | One self-contained page per view: the inlined diagram plus the reasoning cards, with copy / PNG / PDF export |
| `diagrams/svg/*.svg` | The same views as SVG with the diagram XML embedded; they re-open fully editable in diagrams.net |
| `diagrams/drawio/*.drawio` | draw.io source |
| `docs/architecture-one-pager.md` | The one-pager as markdown |
| `docs/decision-record.md` | The 17 decision records, the capability-to-technology table and the package glossary as markdown |
| `specs/part-a..f.json` | Diagram specifications, the source of truth for every view |
| `specs/manifest-a..c.json` | Acts, page titles, subtitles and reasoning cards |
| `specs/adr-onepager.json`, `specs/adr-records-a..b.json` | The one-pager, the decision records, the capability-to-technology table and the glossary |
| `scripts/build.sh` | Rebuilds every deliverable from the specs (Node only) |
| `ask.md` | The requirement |

## Rebuilding

```bash
bash scripts/build.sh
```

Node 20+ and nothing else — no draw.io Desktop, no browser, no network. The build assembles
`specs/views.json` and `specs/manifest.json` from the authoring parts, then runs generate →
validate → route check → SVG → draw.io → HTML → link check, and finally renders the one-pager
and decision record into `diagrams/index.html` and `docs/`. Edit the parts, never the
assembled files.

Current state: **0 validator errors, 0 validator warnings, 146 edges routed with 0 routing
errors and 0 clutter warnings, 379 icons embedded across 21 views, all 166 relative links
resolve.**

## The seven acts

| # | View | What it answers |
|---|---|---|
| 01 | System Context | Who changes AI behaviour, who reads it, and why model providers are outside the line |
| 02 | High-Level Architecture | Six stages from editing a sentence to an answer that carries its digest |
| 03 | Actors and Their Core Journeys | Nine actors, four of them machines, and what each is actually trying to do |
| 04 | Journey — Shipping a Prompt Change | The trough is Release, and it is a data problem rather than a screen problem |
| 05 | Journey — Rolling Back at 3am | The journey the architecture is actually optimised for |
| 06 | Layered Architecture | Seven layers, one of which lives inside somebody else's process |
| 07 | Platform Components | Five planes, and the two edges that are absent on purpose |
| 08 | Integration Surface | Three ways change gets in, one contract by which it gets out |
| 09 | Artefact Lifecycle | Draft to digest to answer, and the point after which nothing is edited |
| 10 | Data Ownership Zones | Five zones sorted by the only question that matters: can this be rebuilt? |
| 11 | Data Model | Twelve entities, one of which uses its content hash as its primary key |
| 12 | Resolution Path | The registry is not on this diagram, because it is not on this path |
| 13 | Promotion and Its Gates | Seven gates, and the one operation that skips the human ones |
| 14 | Propagation and Convergence | Two resolvers, one partitioned, and why it converges anyway |
| 15 | Experiment Assignment and Exposure | Assignment reads nothing, and that is the entire design |
| 16 | Degradation Paths | Seven dependencies, and only one of them costs availability |
| 17 | Deployment Architecture | Why the tier the fleet touches is the smallest one on the page |
| 18 | The Release Loop | Seven steps, and a rollback that re-enters at step four |
| 19 | Observability | Five signal families across six planes, and two empty cells on purpose |
| 20 | Security Trust Zones | Six zones, and the arrow that is missing from the runtime back into control |
| 21 | Identity and Signing | Who proves what, in what order, including the refusal in the middle |

## Evidence and limits

This is a design, not a report on a running system. Every rate, latency, volume, retention and
threshold is a **stated assumption** from `ask.md`, invented to be defensible and arguable
rather than absent, and to be replaced by measurement before build. Four numbers in particular
are the first that real data should overturn: the 2 MB bundle ceiling, which is what makes a
fully resident bundle affordable and therefore makes the whole boundary viable; the 10 s / 60 s
propagation SLO, which decides whether push is load-bearing or merely an optimisation; the
≤ 0.1% assignment-stability budget, which is what every experiment result actually rests on;
and the 11-minute evaluation latency, which decides whether the eval gate sits inside the
promotion flow or in front of it.

Three questions are left genuinely open rather than quietly resolved. Where resolution should
execute is answered for this estate and not in general, with the sidecar alternative and the
condition that flips it recorded rather than dismissed — a targeting-logic defect that cannot
be worked around by a configuration change (ADR-02). Who owns experiment assignment is decided
for the MVP with the hand-over trigger stated in advance, because the argument for delegation
strengthens over time while the cost of migrating rises (ADR-10). And what reproducibility
actually obliges — behavioural equivalence or byte-exactness — is the question that decides
whether this platform stays out of the business of holding user content, and it is named as a
retention ladder rather than settled by default (ADR-14).