[ { "id": "01-system-context", "title": "Prompt & Configuration Registry — System Context", "layout": "context", "colWidth": 260, "system": { "label": "Prompt & Configuration Registry", "sub": "behaviour of AI features" }, "groups": [ { "side": "left", "title": "People who change behaviour", "nodes": [ { "id": "pe", "label": "Prompt engineer", "kind": "actor", "rel": "authors", "dir": "in" }, { "id": "po", "label": "Product owner", "kind": "actor", "rel": "approves", "dir": "in" }, { "id": "oncall", "label": "On-call engineer", "kind": "actor", "rel": "rolls back", "dir": "in" }, { "id": "comp", "label": "Compliance reviewer", "kind": "actor", "rel": "evidence", "dir": "in" } ] }, { "side": "right", "title": "Systems that read it", "nodes": [ { "id": "svc", "label": "AI feature services", "sub": "~300 deployments", "kind": "external", "rel": "resolve by key", "dir": "in" }, { "id": "batch", "label": "Offline jobs", "sub": "pinned digest", "kind": "external", "rel": "replay a digest", "dir": "in" }, { "id": "an", "label": "Experiment analytics", "kind": "external", "rel": "exposures", "kind2": "async" } ] }, { "side": "top", "title": "Where changes come from", "nodes": [ { "id": "git", "label": "Git repository", "sub": "Forgejo", "kind": "external", "rel": "prompt source", "dir": "in" }, { "id": "ci", "label": "CI pipelines", "kind": "external", "rel": "publish via API", "dir": "in" } ] }, { "side": "bottom", "title": "Platform it depends on", "nodes": [ { "id": "idp", "label": "Keycloak", "sub": "human identity", "kind": "security", "rel": "OIDC", "dir": "in" }, { "id": "spire", "label": "SPIRE", "sub": "workload identity", "kind": "security", "rel": "SVIDs", "dir": "in", "icon": "fa5_id_badge" }, { "id": "eval", "label": "Evaluation service", "kind": "external", "rel": "gate verdicts", "dir": "in", "icon": "fa5_microscope" } ] } ], "note": "Model providers are not in scope: the registry names a model, it never calls one.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "02-high-level-architecture", "title": "Prompt & Configuration Registry — High-Level Architecture", "layout": "flow", "chain": true, "align": "middle", "nodeWidth": 210, "stages": [ { "title": "Author", "nodes": [ { "id": "console", "label": "Registry Console", "sub": "React", "kind": "app", "icon": "react" }, { "id": "cli", "label": "CLI & Git sync", "sub": "Forgejo", "kind": "app", "icon": "git" }, { "id": "review", "label": "Review & rationale", "kind": "app", "icon": "fa5_clipboard_check" } ] }, { "title": "Build", "nodes": [ { "id": "flatten", "label": "Flatten fragments", "kind": "app", "icon": "fa5_layer_group" }, { "id": "validate", "label": "Schema & policy", "kind": "app", "icon": "fa5_check_double" }, { "id": "seal", "label": "Digest & sign", "sub": "SHA-256", "kind": "security", "icon": "fa5_stamp" } ] }, { "title": "Release", "nodes": [ { "id": "gates", "label": "Gates & approvals", "kind": "decision", "icon": "fa5_balance_scale" }, { "id": "pointer", "label": "Environment pointer", "sub": "etcd", "kind": "store", "icon": "fa5_map_signs" }, { "id": "rollout", "label": "Rollout & experiment", "kind": "app", "icon": "fa5_flask" } ] }, { "title": "Distribute", "nodes": [ { "id": "oci", "label": "Artefact store", "sub": "OCI registry", "kind": "store", "icon": "fa5_box" }, { "id": "bus", "label": "Change bus", "sub": "NATS JetStream", "kind": "queue", "icon": "fa5_bullhorn" }, { "id": "poll", "label": "Poll backstop", "sub": "30 s", "kind": "app", "icon": "fa5_sync_alt" } ] }, { "title": "Resolve", "nodes": [ { "id": "sdk", "label": "Resolver SDK", "sub": "in the app process", "kind": "app", "icon": "fa5_cube" }, { "id": "cache", "label": "Resident bundle", "sub": "verified, ≤ 2 MB", "kind": "store", "icon": "fa5_memory" }, { "id": "assign", "label": "Assignment function", "sub": "pure, no lookup", "kind": "app", "icon": "fa5_random" } ] }, { "title": "Prove", "nodes": [ { "id": "exp", "label": "Exposure pipeline", "sub": "Kafka → ClickHouse", "kind": "queue", "icon": "kafka" }, { "id": "readout", "label": "Experiment readout", "kind": "app", "icon": "fa5_chart_line" }, { "id": "audit", "label": "Audit ledger", "sub": "WORM, 7 years", "kind": "store", "icon": "fa5_archive" } ] } ], "edges": [ { "from": "sdk", "to": "exp", "label": "exposure", "kind": "async" }, { "from": "gates", "to": "audit", "label": "every verdict", "kind": "async", "route": "gutter" } ], "note": "The only thing crossing from Release to Resolve is an immutable signed bundle and a pointer to it.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "03-actors-and-journeys", "title": "Who the Registry Is For, and What They Get To Do", "layout": "actors", "cardWidth": 300, "groups": [ { "title": "People who change what the model says", "kind": "boundary", "actors": [ { "id": "pe", "label": "Prompt engineer", "sub": "~40 across product teams", "goal": "Change the assistant's wording today, not in next week's release, and know before a customer sees it that I have not broken something.", "journeys": [ { "id": "j-ship", "label": "Ship a prompt change", "sub": "~200 / day" }, { "label": "Compare two wordings" }, { "label": "Pin a model version" } ] }, { "id": "po", "label": "Product owner", "sub": "1 per feature", "goal": "Approve what goes live without having to read a diff of a service I do not own, and see what it did afterwards.", "journeys": [ { "label": "Approve a promotion" }, { "label": "Read an experiment out" } ] }, { "id": "ds", "label": "Data scientist", "sub": "experiment owner", "goal": "Run two prompts against real traffic and get a number I am willing to defend, not a screenshot of three good answers.", "journeys": [ { "label": "Define an experiment" }, { "label": "Hold a variant out" } ] } ] }, { "title": "People who keep it standing", "kind": "boundary", "actors": [ { "id": "oncall", "label": "On-call engineer", "sub": "24×7 rota", "goal": "Make it stop, before I understand why — and be certain afterwards what was live when it went wrong.", "journeys": [ { "id": "j-rollback", "label": "Roll back at 3am", "sub": "target < 30 s" }, { "label": "Pull a kill switch" } ] }, { "id": "plat", "label": "Platform engineer", "sub": "owns the registry", "goal": "Be able to take my own control plane down for an afternoon without a single product noticing.", "journeys": [ { "label": "Upgrade the control plane" }, { "label": "Rotate the signing key" } ] } ] }, { "title": "People who ask afterwards", "kind": "boundary", "actors": [ { "id": "comp", "label": "Compliance reviewer", "sub": "quarterly, plus incidents", "goal": "Be shown exactly what configuration produced a specific answer on a specific day, signed, without taking anybody's word for it.", "journeys": [ { "label": "Recover a past configuration" }, { "label": "Export signed evidence" } ] }, { "id": "supp", "label": "Support lead", "sub": "first to notice", "goal": "Tell whether the answer a customer is complaining about came from a change we made this morning.", "journeys": [ { "label": "Trace an answer to a digest" } ] } ] }, { "title": "Machines in the cast", "kind": "cloud", "actors": [ { "id": "svc", "label": "AI feature service", "kind": "external", "sub": "~300 deployments", "goal": "Get an answer to \"what am I supposed to say?\" in under a millisecond, and keep getting one when the registry is down.", "journeys": [ { "label": "Resolve a key" }, { "label": "Serve on a stale bundle" } ] }, { "id": "evalsvc", "label": "Evaluation service", "kind": "external", "sub": "gate input", "goal": "Be asked for a verdict on a specific digest, not on \"the latest prompt\".", "journeys": [ { "label": "Return a gate verdict" } ] }, { "id": "cijob", "label": "CI pipeline", "kind": "platform", "sub": "per product repo", "goal": "Publish a version from the repo that owns the prompt, and fail the build when it will not validate.", "journeys": [ { "label": "Publish from a merge" } ] } ] } ], "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "04-journey-ship-a-prompt-change", "title": "Journey — Prompt Engineer Ships a Wording Change", "layout": "journey", "cellWidth": 215, "actor": { "label": "Prompt engineer", "sub": "billing assistant", "goal": "Change what the assistant says about refunds, and know it is safe before a customer sees it", "trigger": "Support reports the assistant apologising for charges the customer was never billed", "success": "New wording live for 5% of conversations, with the old one one click away" }, "phases": [ { "title": "Notice", "sub": "outside the tool" }, { "title": "Draft" }, { "title": "Review" }, { "title": "Release", "moment": true }, { "title": "Watch" } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Reads the ticket" }, { "label": "Finds the digest" } ], [ { "label": "Edits the refund block" }, { "label": "Writes the rationale" } ], [ { "label": "Opens for review" }, { "label": "Answers a comment" } ], [ { "label": "Promotes to prod" }, { "label": "Sets 5% rollout" } ], [ { "label": "Watches refusal rate" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [ { "label": "Resolves digest → version" } ], [ { "label": "Flattens, validates" }, { "label": "Diffs against live" } ], [ { "label": "Runs the eval gate" }, { "label": "Blocks on threshold" } ], [ { "label": "Signs, stores, points" }, { "label": "Fans out the notice" } ], [ { "label": "Reports convergence" }, { "label": "Streams exposures" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Confident", "Fine", "Anxious" ], "points": [ "Fine", "Confident", "Fine", "Anxious", "Confident" ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [ { "label": "Which prompt said that?" } ], [], [ { "label": "Eval takes 11 minutes" } ], [ { "label": "Is it live everywhere yet?" } ], [ { "label": "Signal lags the change" } ] ] }, { "title": "What answers it", "kind": "gain", "cells": [ [ { "label": "Digest on every answer" } ], [], [ { "label": "Gate verdict bound to digest" } ], [ { "label": "Convergence metric, view 14" } ], [ { "label": "Rollback is one action" } ] ] } ], "chain": true, "note": "The trough is Release: nobody trusts a change they cannot see land. View 14 is the answer.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "05-journey-rollback-at-3am", "title": "Journey — On-Call Engineer Rolls Back at 3am", "layout": "journey", "cellWidth": 215, "actor": { "label": "On-call engineer", "sub": "does not own the prompt", "goal": "Make it stop, before understanding why", "trigger": "Paged: refusal rate on the billing assistant up 9× in twenty minutes", "success": "Behaviour back to yesterday's inside a minute, with every bit of evidence still intact" }, "phases": [ { "title": "Page" }, { "title": "Orient", "moment": true }, { "title": "Decide", "moment": true }, { "title": "Revert" }, { "title": "Confirm" } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Opens the alert" } ], [ { "label": "Asks what changed" }, { "label": "Reads the digest history" } ], [ { "label": "Picks last known good" } ], [ { "label": "Confirms rollback" } ], [ { "label": "Checks the metric" }, { "label": "Hands to the owner" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [ { "label": "Alert names the key" } ], [ { "label": "Lists last 10 live digests" }, { "label": "Shows serving windows" } ], [ { "label": "Diffs the two versions" } ], [ { "label": "Pointer write, 2 s" }, { "label": "Notice + poll backstop" } ], [ { "label": "99% converged at 8 s" }, { "label": "Audit entry written" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "In control", "Coping", "Lost" ], "points": [ "Coping", "Lost", "Coping", "Coping", "In control" ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [], [ { "label": "Which of six changes?" }, { "label": "Is the fleet even uniform?" } ], [ { "label": "No approver awake" } ], [], [ { "label": "Signal lags 10 minutes" } ] ] }, { "title": "What answers it", "kind": "gain", "cells": [ [], [ { "label": "Serving windows per digest" }, { "label": "Skew is a metric, not a guess" } ], [ { "label": "Rollback needs no approval" } ], [ { "label": "Same path as promotion" } ], [ { "label": "Kill switch if it is not it" } ] ] } ], "chain": true, "note": "Orient is the trough, and it is a data problem, not a UX one: the registry must already know which digest served which window.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "06-layered-architecture", "title": "Layered Architecture", "layout": "bands", "layerHeaderWidth": 175, "bands": [ { "name": "Experience", "nodes": [ { "id": "console", "label": "Registry Console", "sub": "React", "kind": "app", "icon": "react" }, { "id": "cli", "label": "CLI", "kind": "app", "icon": "fa5_terminal" }, { "id": "gitsync", "label": "Git sync", "sub": "Forgejo", "kind": "integration", "icon": "git" }, { "id": "api", "label": "Config API", "sub": "Go", "kind": "integration", "icon": "fa5_plug" } ] }, { "name": "Release control", "nodes": [ { "id": "gate", "label": "Gate engine", "kind": "decision", "icon": "fa5_balance_scale" }, { "id": "ptrctl", "label": "Pointer controller", "kind": "app", "icon": "fa5_map_signs" }, { "id": "expctl", "label": "Experiment controller", "kind": "app", "icon": "fa5_flask" }, { "id": "auditw", "label": "Audit writer", "kind": "security", "icon": "fa5_file_signature" } ] }, { "name": "Build & seal", "nodes": [ { "id": "flat", "label": "Fragment resolver", "kind": "app", "icon": "fa5_layer_group" }, { "id": "val", "label": "Schema & policy", "kind": "app", "icon": "fa5_check_double" }, { "id": "scan", "label": "Secret scanner", "kind": "security", "icon": "fa5_search" }, { "id": "sign", "label": "Signer", "sub": "OpenBao", "kind": "security", "icon": "fa5_stamp" } ] }, { "name": "Distribution", "nodes": [ { "id": "oci", "label": "Artefact store", "sub": "OCI registry", "kind": "store", "icon": "fa5_box" }, { "id": "obj", "label": "Object store", "sub": "MinIO", "kind": "store", "icon": "minio" }, { "id": "etcd", "label": "Pointer store", "sub": "etcd, linearisable", "kind": "store", "icon": "fa5_map_signs" }, { "id": "bus", "label": "Change bus", "sub": "NATS JetStream", "kind": "queue", "icon": "fa5_bullhorn" } ] }, { "name": "Resolution", "nodes": [ { "id": "sdk", "label": "Resolver SDK", "sub": "Go · Python · TS", "kind": "app", "icon": "fa5_cube" }, { "id": "cache", "label": "Resident bundle", "kind": "store", "icon": "fa5_memory" }, { "id": "rules", "label": "Targeting evaluator", "kind": "app", "icon": "fa5_sitemap" }, { "id": "assign", "label": "Assignment function", "kind": "app", "icon": "fa5_random" } ] }, { "name": "Evidence", "nodes": [ { "id": "otel", "label": "Exposure collector", "sub": "OpenTelemetry", "kind": "integration", "icon": "opentelemetry" }, { "id": "kfk", "label": "Buffer", "sub": "Kafka", "kind": "queue", "icon": "kafka" }, { "id": "ch", "label": "Exposure store", "sub": "ClickHouse", "kind": "store", "icon": "clickhouse" }, { "id": "ledger", "label": "Audit ledger", "sub": "WORM", "kind": "store", "icon": "fa5_archive" } ] }, { "name": "Platform", "nodes": [ { "id": "k8s", "label": "Kubernetes", "kind": "platform", "icon": "kubernetes" }, { "id": "kc", "label": "Keycloak", "kind": "security", "icon": "keycloak" }, { "id": "spire", "label": "SPIRE", "kind": "security", "icon": "fa5_id_badge" }, { "id": "bao", "label": "OpenBao", "sub": "key custody", "kind": "security", "icon": "fa5_key" }, { "id": "prom", "label": "Prometheus", "kind": "platform", "icon": "prometheus" } ] } ], "edges": [ { "from": "api", "to": "gate", "label": "promote" }, { "from": "ptrctl", "to": "etcd", "label": "pointer write" }, { "from": "bus", "to": "sdk", "label": "change notice", "kind": "async" }, { "from": "sdk", "to": "otel", "label": "exposure", "kind": "async" } ], "note": "Resolution sits inside the application process. Nothing in it calls anything above Distribution.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "07-platform-components", "title": "Platform Components — Container View", "layout": "nested", "canvas": { "width": 1750 }, "boxes": [ { "title": "Registry platform — Kubernetes (self-hosted)", "kind": "onprem", "dir": "col", "children": [ { "title": "Authoring plane — transactional, may be unavailable", "kind": "boundary", "nodes": [ { "id": "console", "label": "Registry Console", "sub": "React", "kind": "app", "icon": "react" }, { "id": "api", "label": "Config API", "sub": "Go", "kind": "integration", "icon": "fa5_plug" }, { "id": "review", "label": "Review service", "kind": "app", "icon": "fa5_clipboard_check" }, { "id": "pg", "label": "Authoring store", "sub": "PostgreSQL / Patroni", "kind": "store", "icon": "postgresql" } ] }, { "title": "Build plane — everything happens here, nothing at resolve time", "kind": "boundary", "nodes": [ { "id": "bctl", "label": "Build controller", "sub": "Argo Workflows", "kind": "app", "icon": "argocd" }, { "id": "val", "label": "Validator", "sub": "schema · policy · lint", "kind": "app", "icon": "fa5_check_double" }, { "id": "scan", "label": "Secret scanner", "kind": "security", "icon": "fa5_search" }, { "id": "sign", "label": "Signer", "sub": "OpenBao transit", "kind": "security", "icon": "fa5_stamp" } ] }, { "title": "Release plane — the only writer of pointers", "kind": "boundary", "nodes": [ { "id": "gate", "label": "Gate engine", "kind": "decision", "icon": "fa5_balance_scale" }, { "id": "ptrctl", "label": "Pointer controller", "kind": "app", "icon": "fa5_map_signs" }, { "id": "expctl", "label": "Experiment controller", "kind": "app", "icon": "fa5_flask" }, { "id": "auditw", "label": "Audit writer", "kind": "security", "icon": "fa5_file_signature" } ] }, { "title": "Distribution — read-only to everything downstream", "kind": "boundary", "nodes": [ { "id": "oci", "label": "Artefact registry", "sub": "OCI, content-addressed", "kind": "store", "icon": "fa5_box" }, { "id": "obj", "label": "Object store", "sub": "MinIO, Object Lock", "kind": "store", "icon": "minio" }, { "id": "etcd", "label": "Pointer store", "sub": "etcd, 3-node quorum", "kind": "store", "icon": "fa5_map_signs" }, { "id": "bus", "label": "Change bus", "sub": "NATS JetStream", "kind": "queue", "icon": "fa5_bullhorn" } ] }, { "title": "Evidence plane — droppable telemetry, durable audit", "kind": "boundary", "nodes": [ { "id": "otel", "label": "Exposure collector", "kind": "integration", "icon": "opentelemetry" }, { "id": "kfk", "label": "Buffer", "sub": "Kafka", "kind": "queue", "icon": "kafka" }, { "id": "ch", "label": "Exposure store", "sub": "ClickHouse", "kind": "store", "icon": "clickhouse" }, { "id": "ledger", "label": "Audit ledger", "sub": "WORM, 7 years", "kind": "store", "icon": "fa5_archive" } ] } ] } ], "outside": [ { "id": "app", "label": "AI feature service", "sub": "resolver SDK inside", "kind": "external", "icon": "fa5_cube" }, { "id": "git", "label": "Git repository", "sub": "Forgejo", "kind": "external", "icon": "git" }, { "id": "eval", "label": "Evaluation service", "kind": "external", "icon": "fa5_microscope" }, { "id": "kc", "label": "Keycloak", "kind": "security", "icon": "keycloak" }, { "id": "spire", "label": "SPIRE", "kind": "security", "icon": "fa5_id_badge" } ], "edges": [ { "from": "api", "to": "bctl", "label": "build version" }, { "from": "ptrctl", "to": "etcd", "label": "pointer write" }, { "from": "oci", "to": "app", "label": "pull by digest", "kind": "async" } ], "note": "Omitted for legibility: the Git webhook into the Config API, the gate's call to the evaluation service, and the signer's push into the artefact registry — all drawn on views 08 and 09. Absent by design: any edge from the authoring store downstream, or from the application into the control plane.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "08-integration-surface", "title": "Integration Surface", "layout": "hub", "left": { "title": "Where change enters", "nodes": [ { "id": "console", "label": "Console & CLI", "kind": "app", "rel": "OIDC", "icon": "react" }, { "id": "git", "label": "Git & CI pipelines", "kind": "external", "rel": "webhook", "kind2": "async", "icon": "git" }, { "id": "eval", "label": "Evaluation service", "kind": "external", "rel": "verdict", "icon": "fa5_microscope" } ] }, "centre": { "title": "Prompt & Configuration Registry", "nodes": [ { "id": "core", "label": "Registry control plane", "sub": "author · build · release" } ] }, "right": { "title": "Where it is consumed", "nodes": [ { "id": "sdk", "label": "Resolver SDK fleet", "sub": "~300 services", "kind": "external", "rel": "pull", "dir": "out", "icon": "fa5_cube" }, { "id": "an", "label": "Experiment analytics", "kind": "external", "rel": "events", "dir": "out", "kind2": "async", "icon": "fa5_chart_line" }, { "id": "arch", "label": "Audit archive", "kind": "external", "rel": "evidence", "dir": "out", "kind2": "batch", "icon": "fa5_archive" } ] }, "note": "Three inbound interfaces, one outbound contract: a signed bundle addressed by digest. Metrics and paging ride the platform observability channel, on view 19.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "09-artefact-lifecycle", "title": "Artefact Lifecycle — Draft to Digest to Answer", "layout": "flow", "chain": true, "align": "middle", "nodeWidth": 205, "stages": [ { "title": "Authored", "nodes": [ { "id": "text", "label": "Prompt text", "kind": "app", "icon": "fa5_file_alt" }, { "id": "frag", "label": "Shared fragments", "kind": "app", "icon": "fa5_layer_group" }, { "id": "vars", "label": "Variable schema", "kind": "app", "icon": "fa5_code" } ] }, { "title": "Built", "nodes": [ { "id": "flat", "label": "Flatten & canonicalise", "kind": "app", "icon": "fa5_compress_alt" }, { "id": "check", "label": "Validate & lint", "kind": "app", "icon": "fa5_check_double" }, { "id": "pin", "label": "Pin model alias", "sub": "alias → snapshot", "kind": "app", "icon": "fa5_thumbtack" } ] }, { "title": "Sealed", "nodes": [ { "id": "dig", "label": "Digest", "sub": "SHA-256", "kind": "security", "icon": "fa5_fingerprint" }, { "id": "sig", "label": "Sign", "sub": "OpenBao transit", "kind": "security", "icon": "fa5_stamp" }, { "id": "push", "label": "Push to artefact store", "kind": "store", "icon": "fa5_box" } ] }, { "title": "Released", "nodes": [ { "id": "gate", "label": "Gates & approval", "kind": "decision", "icon": "fa5_balance_scale" }, { "id": "ptr", "label": "Pointer write", "sub": "etcd", "kind": "store", "icon": "fa5_map_signs" }, { "id": "aud", "label": "Audit entry", "kind": "security", "icon": "fa5_file_signature" } ] }, { "title": "Distributed", "nodes": [ { "id": "notice", "label": "Change notice", "sub": "NATS", "kind": "queue", "icon": "fa5_bullhorn" }, { "id": "pull", "label": "Pull by digest", "kind": "app", "icon": "fa5_download" }, { "id": "ver", "label": "Verify signature", "kind": "security", "icon": "fa5_shield_alt" } ] }, { "title": "Served", "nodes": [ { "id": "res", "label": "Resident bundle", "kind": "store", "icon": "fa5_memory" }, { "id": "ans", "label": "Answer", "kind": "app", "icon": "fa5_comment_dots" }, { "id": "stamp", "label": "Digest on the answer", "kind": "security", "icon": "fa5_tag" } ] } ], "edges": [ { "from": "ver", "to": "res", "label": "accept" }, { "from": "ver", "to": "ptr", "label": "reject: keep previous", "kind": "error", "route": "gutter" } ], "note": "Nothing is edited after Sealed. Promotion, rollback and replay all address the same digest.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "10-data-ownership-zones", "title": "Data Ownership Zones — What Can Be Rebuilt, and What Cannot", "layout": "nested", "canvas": { "width": 1700 }, "boxes": [ { "title": "Registry platform", "kind": "onprem", "dir": "col", "children": [ { "title": "Released truth — immutable, never rebuilt, RPO 0", "kind": "trust", "nodes": [ { "id": "oci", "label": "Signed bundles", "sub": "OCI, by digest", "kind": "store", "icon": "fa5_box" }, { "id": "obj", "label": "Bundle blobs", "sub": "MinIO, Object Lock", "kind": "store", "icon": "minio" }, { "id": "ledger", "label": "Audit ledger", "sub": "WORM, 7 years", "kind": "store", "icon": "fa5_archive" } ] }, { "title": "Control state — small, linearisable, the only thing promotion writes", "kind": "boundary", "nodes": [ { "id": "ptr", "label": "Environment pointers", "sub": "key → digest", "kind": "store", "icon": "fa5_map_signs" }, { "id": "roll", "label": "Rollout percentages", "kind": "store", "icon": "fa5_percentage" }, { "id": "kill", "label": "Kill switches", "kind": "store", "icon": "fa5_toggle_on" } ] }, { "title": "Authoring truth — transactional, rebuildable from Git, RPO 5 min", "kind": "boundary", "nodes": [ { "id": "pg", "label": "Drafts & reviews", "sub": "PostgreSQL", "kind": "store", "icon": "postgresql" }, { "id": "own", "label": "Ownership & grants", "kind": "store", "icon": "fa5_users" }, { "id": "expdef", "label": "Experiment definitions", "kind": "store", "icon": "fa5_flask" } ] }, { "title": "Derived — lossy-tolerant, rebuildable from the event stream", "kind": "lane", "nodes": [ { "id": "ch", "label": "Exposure events", "sub": "ClickHouse, 90 d hot", "kind": "store", "icon": "clickhouse" }, { "id": "ro", "label": "Readout materialisations", "kind": "store", "icon": "fa5_chart_line" }, { "id": "met", "label": "Convergence metrics", "sub": "Prometheus", "kind": "store", "icon": "prometheus" } ] } ] }, { "title": "Application runtime — ephemeral, rebuildable from the artefact store", "kind": "lane", "dir": "row", "children": [ { "title": "Every AI feature pod", "kind": "plain", "nodes": [ { "id": "cache", "label": "Resident bundle", "sub": "verified, in memory", "kind": "store", "icon": "fa5_memory" }, { "id": "baked", "label": "Baked-in default", "sub": "image build time", "kind": "store", "icon": "docker" } ] } ] } ], "outside": [ { "id": "git", "label": "Git remote", "sub": "authored source", "kind": "external", "icon": "git" }, { "id": "tape", "label": "Offsite WORM copy", "kind": "external", "icon": "fa5_hdd" } ], "edges": [ { "from": "oci", "to": "cache", "label": "refills", "kind": "async" }, { "from": "ledger", "to": "tape", "label": "replicated", "kind": "batch" } ], "note": "Only two zones cannot be rebuilt: released bundles and the audit ledger. Everything else is a cache with a longer name.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "11-data-model", "title": "Data Model", "layout": "er", "canvas": { "width": 1700, "cols": 4 }, "rowGap": 260, "entities": [ { "id": "key", "name": "config_key", "kind": "store", "row": 0, "col": 0, "attrs": [ "key_id PK", "namespace", "owning_group", "unit_type user|session|tenant", "confidential bool", "safe_default_digest" ] }, { "id": "ver", "name": "version", "kind": "store", "row": 0, "col": 1, "attrs": [ "digest PK sha256", "key_id FK -> config_key", "author", "rationale required", "model_pin", "state draft|review|published", "created_at" ] }, { "id": "frag", "name": "fragment", "kind": "store", "row": 0, "col": 2, "attrs": [ "fragment_id PK", "digest content-addressed", "name", "owning_group" ] }, { "id": "var", "name": "variable", "kind": "store", "row": 0, "col": 3, "attrs": [ "variable_id PK", "digest FK -> version", "name", "type", "required", "default" ] }, { "id": "ptr", "name": "environment_pointer", "kind": "store", "row": 1, "col": 0, "attrs": [ "key_id FK -> config_key", "environment PK part", "digest FK -> version", "rollout_pct", "killed bool", "updated_at" ] }, { "id": "prom", "name": "promotion", "kind": "store", "row": 1, "col": 1, "attrs": [ "promotion_id PK", "key_id FK -> config_key", "from_digest", "to_digest FK -> version", "environment", "actor", "kind promote|rollback|kill", "at" ] }, { "id": "appr", "name": "approval", "kind": "store", "row": 1, "col": 2, "attrs": [ "approval_id PK", "promotion_id FK -> promotion", "approver", "gate", "verdict", "at" ] }, { "id": "gate", "name": "gate_verdict", "kind": "store", "row": 1, "col": 3, "attrs": [ "verdict_id PK", "digest FK -> version", "gate_name", "score", "threshold", "passed bool" ] }, { "id": "exp", "name": "experiment", "kind": "store", "row": 2, "col": 0, "attrs": [ "experiment_id PK", "key_id FK -> config_key", "environment", "salt immutable", "primary_metric", "min_exposures", "exclusion_group", "state" ] }, { "id": "vart", "name": "variant", "kind": "store", "row": 2, "col": 1, "attrs": [ "variant_id PK", "experiment_id FK -> experiment", "digest FK -> version", "weight_pct" ] }, { "id": "expo", "name": "exposure", "kind": "store", "row": 2, "col": 2, "attrs": [ "exposure_id PK", "experiment_id FK -> experiment", "variant_id FK -> variant", "unit_hash", "digest", "at 90 d hot" ] }, { "id": "aud", "name": "audit_event", "kind": "store", "row": 2, "col": 3, "attrs": [ "event_id PK", "subject digest|key|promotion", "actor", "action", "at append-only", "prev_hash" ] } ], "relations": [ { "from": "key", "to": "ver", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "ver", "to": "frag", "label": "N : M", "from_side": "e", "to_side": "w" }, { "from": "ver", "to": "var", "label": "1 : N", "from_side": "n3", "to_side": "n" }, { "from": "key", "to": "ptr", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "ptr", "to": "prom", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "prom", "to": "appr", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "ver", "to": "gate", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "exp", "to": "vart", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "vart", "to": "expo", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "prom", "to": "aud", "label": "1 : N", "kind": "optional", "from_side": "s3", "to_side": "n3" }, { "from": "ptr", "to": "exp", "label": "1 : N", "from_side": "s", "to_side": "n" } ], "note": "digest is the primary key of a version, not a surrogate: identity and content are the same thing. An experiment is scoped to a key and an environment, so it hangs off the pointer.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "12-resolution-path", "title": "Resolution Path — What Happens Inside One Request", "layout": "sequence", "lifelines": [ { "id": "app", "label": "AI feature service", "kind": "app" }, { "id": "sdk", "label": "Resolver SDK", "kind": "app" }, { "id": "cache", "label": "Resident bundle", "kind": "store" }, { "id": "assign", "label": "Assignment fn", "kind": "app" }, { "id": "prov", "label": "Model provider", "kind": "external" }, { "id": "buf", "label": "Exposure buffer", "kind": "queue" } ], "messages": [ { "from": "app", "to": "sdk", "label": "resolve(key, context)", "kind": "call" }, { "from": "sdk", "to": "cache", "label": "read bundle (in-process)", "kind": "call" }, { "from": "cache", "to": "sdk", "label": "rules + variants", "kind": "return" }, { "from": "sdk", "to": "sdk", "label": "match targeting rule", "kind": "self" }, { "from": "sdk", "to": "assign", "label": "hash(unit, salt)", "kind": "call" }, { "from": "assign", "to": "sdk", "label": "variant B", "kind": "return" }, { "from": "sdk", "to": "app", "label": "config + digest + rule id", "kind": "return" }, { "from": "app", "to": "prov", "label": "inference on pinned model", "kind": "call" }, { "from": "prov", "to": "app", "label": "completion", "kind": "return" }, { "from": "app", "to": "buf", "label": "exposure (once per window)", "kind": "async" }, { "from": "app", "to": "app", "label": "record digest on the response", "kind": "self" }, { "from": "sdk", "to": "app", "label": "bundle unverified → safe default", "kind": "error" } ], "note": "No message leaves the process before the answer is decided. The registry is not on this diagram because it is not on this path.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "13-promotion-and-gates", "title": "Promotion — The Gates a Change Passes Through", "layout": "flow", "chain": true, "align": "middle", "nodeWidth": 200, "stages": [ { "title": "Request", "nodes": [ { "id": "req", "label": "Promote to production", "sub": "one key or a set", "kind": "app", "icon": "fa5_rocket" }, { "id": "atomic", "label": "Atomic set", "sub": "all or none", "kind": "app", "icon": "fa5_object_group" } ] }, { "title": "Automatic gates", "nodes": [ { "id": "g1", "label": "Schema & variables", "kind": "decision", "icon": "fa5_check_double" }, { "id": "g2", "label": "Policy lint", "sub": "safety settings", "kind": "decision", "icon": "fa5_shield_alt" }, { "id": "g3", "label": "Secret scan", "kind": "decision", "icon": "fa5_search" }, { "id": "g4", "label": "Eval threshold", "sub": "verdict on this digest", "kind": "decision", "icon": "fa5_microscope" } ] }, { "title": "Human gates", "nodes": [ { "id": "g5", "label": "Second approver", "kind": "decision", "icon": "fa5_user_shield" }, { "id": "g6", "label": "Owning group", "sub": "high-risk keys", "kind": "decision", "icon": "fa5_users_cog" }, { "id": "g7", "label": "Open incident?", "kind": "decision", "icon": "fa5_exclamation_triangle" } ] }, { "title": "Commit", "nodes": [ { "id": "ptr", "label": "Pointer write", "sub": "etcd, linearisable", "kind": "store", "icon": "fa5_map_signs" }, { "id": "aud", "label": "Audit entry", "sub": "actor, rationale, digest", "kind": "security", "icon": "fa5_file_signature" } ] }, { "title": "Outcome", "nodes": [ { "id": "live", "label": "Live at declared %", "kind": "app", "icon": "fa5_check_circle" }, { "id": "held", "label": "Held", "sub": "awaiting a person", "kind": "risk", "icon": "fa5_hourglass_half" }, { "id": "rej", "label": "Rejected", "sub": "reason on the digest", "kind": "risk", "icon": "fa5_times_circle" } ] } ], "edges": [ { "from": "g4", "to": "rej", "label": "below threshold", "kind": "error", "route": "gutter" }, { "from": "g7", "to": "held", "label": "incident open", "kind": "error" }, { "from": "req", "to": "aud", "label": "recorded on request", "kind": "async", "route": "gutter" } ], "note": "Rollback enters at Commit and skips the human gates. That is the only difference between the two operations.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "14-propagation-and-convergence", "title": "Propagation — How a Change Reaches a Fleet, and How Anyone Knows", "layout": "sequence", "lifelines": [ { "id": "ctl", "label": "Pointer controller", "kind": "app" }, { "id": "etcd", "label": "etcd", "kind": "store" }, { "id": "bus", "label": "NATS JetStream", "kind": "queue" }, { "id": "ra", "label": "Resolver A", "kind": "app" }, { "id": "rb", "label": "Resolver B (partitioned)", "kind": "app" }, { "id": "oci", "label": "Artefact store", "kind": "store" }, { "id": "prom", "label": "Convergence metric", "kind": "platform" } ], "messages": [ { "from": "ctl", "to": "etcd", "label": "compare-and-set pointer", "kind": "call" }, { "from": "etcd", "to": "ctl", "label": "committed, rev 4812", "kind": "return" }, { "from": "ctl", "to": "bus", "label": "publish notice", "kind": "async" }, { "from": "bus", "to": "ra", "label": "key K → digest d9f", "kind": "async" }, { "from": "ra", "to": "oci", "label": "pull by digest", "kind": "call" }, { "from": "ra", "to": "ra", "label": "verify signature", "kind": "self" }, { "from": "ra", "to": "prom", "label": "serving d9f (t+3 s)", "kind": "async" }, { "from": "rb", "to": "rb", "label": "notice never arrived", "kind": "error" }, { "from": "rb", "to": "etcd", "label": "poll backstop, 30 s", "kind": "call" }, { "from": "rb", "to": "oci", "label": "pull by digest", "kind": "call" }, { "from": "rb", "to": "prom", "label": "serving d9f (t+41 s)", "kind": "async" }, { "from": "prom", "to": "ctl", "label": "99% at 8 s, 100% at 41 s", "kind": "return" } ], "note": "The poll is what guarantees convergence; the notice only makes it fast. Losing the bus costs latency, never correctness.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "15-experiment-assignment", "title": "Experiment Assignment and Exposure", "layout": "swimlane", "laneHeaderWidth": 190, "stages": [ "Request", "Eligibility", "Assignment", "Serve", "Record", "Read out" ], "lanes": [ { "title": "Resolver (in-process)", "cells": [ [ { "label": "resolve(key, unit)", "kind": "app", "icon": "fa5_cube" } ], [ { "label": "rule match", "kind": "app", "icon": "fa5_sitemap" } ], [ { "label": "hash(unit, salt)", "kind": "app", "icon": "fa5_random" } ], [ { "label": "variant digest", "kind": "app", "icon": "fa5_tag" } ], [ { "label": "once per window", "kind": "app", "icon": "fa5_clock" } ], [] ] }, { "title": "Exclusion", "cells": [ [], [ { "label": "exclusion check", "kind": "decision", "icon": "fa5_ban" } ], [ { "label": "holdout reserved", "kind": "app", "icon": "fa5_user_slash" } ], [], [], [ { "label": "holdout vs treated", "kind": "app", "icon": "fa5_balance_scale" } ] ] }, { "title": "Control plane", "cells": [ [], [ { "label": "definition", "kind": "store", "icon": "fa5_flask" } ], [ { "label": "salt immutable", "kind": "store", "icon": "fa5_lock" } ], [ { "label": "weights live", "kind": "store", "icon": "fa5_sliders_h" } ], [], [ { "label": "min exposures?", "kind": "decision", "icon": "fa5_tasks" } ] ] }, { "title": "Evidence", "cells": [ [], [], [], [], [ { "label": "exposure event", "kind": "queue", "icon": "kafka" }, { "label": "drop count kept", "kind": "risk", "icon": "fa5_exclamation_triangle" } ], [ { "label": "diff + interval", "kind": "app", "icon": "fa5_chart_line" }, { "label": "loss rate stated", "kind": "app", "icon": "fa5_percentage" } ] ] } ], "note": "Assignment reads nothing. An empty cell in the Exclusion lane at Serve is deliberate: weights change, assignment does not.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "16-degradation-paths", "title": "Degradation — What Each Dependency Costs When It Goes", "layout": "swimlane", "laneHeaderWidth": 200, "stages": [ "Healthy", "Degraded", "Failed", "Recovery" ], "lanes": [ { "title": "Control plane", "cells": [ [ { "label": "authoring, gates, promotion", "kind": "app" } ], [ { "label": "read-only authoring", "kind": "app", "icon": "fa5_eye" } ], [ { "label": "no new releases", "kind": "risk", "icon": "fa5_ban" } ], [ { "label": "resumes, no restart", "kind": "app", "icon": "fa5_sync_alt" } ] ] }, { "title": "Pointer store (etcd)", "cells": [ [ { "label": "linearisable pointer writes", "kind": "store" } ], [ { "label": "poll backstop stale", "kind": "app", "icon": "fa5_hourglass_half" } ], [ { "label": "fleet frozen on last digest", "kind": "risk", "icon": "fa5_lock" } ], [ { "label": "converges on next poll", "kind": "app", "icon": "fa5_sync_alt" } ] ] }, { "title": "Change bus (NATS)", "cells": [ [ { "label": "notice in ≤ 3 s", "kind": "queue" } ], [ { "label": "propagation falls to 30 s", "kind": "app", "icon": "fa5_clock" } ], [ { "label": "poll is the only path", "kind": "app", "icon": "fa5_redo" } ], [ { "label": "no replay needed", "kind": "app", "icon": "fa5_check_circle" } ] ] }, { "title": "Artefact store", "cells": [ [ { "label": "pull by digest", "kind": "store" } ], [ { "label": "new pods use baked default", "kind": "app", "icon": "docker" } ], [ { "label": "running pods unaffected", "kind": "app", "icon": "fa5_memory" } ], [ { "label": "pull on next notice", "kind": "app", "icon": "fa5_download" } ] ] }, { "title": "Signature / trust", "cells": [ [ { "label": "verified on load", "kind": "security" } ], [], [ { "label": "FAIL CLOSED: reject bundle", "kind": "risk", "icon": "fa5_shield_alt" } ], [ { "label": "keep previous, page someone", "kind": "security", "icon": "fa5_bell" } ] ] }, { "title": "Exposure pipeline", "cells": [ [ { "label": "500 M events/day", "kind": "queue", "icon": "kafka" } ], [ { "label": "sampled down", "kind": "app", "icon": "fa5_percentage" } ], [ { "label": "dropped, count kept", "kind": "risk", "icon": "fa5_trash_alt" } ], [ { "label": "readout declares loss rate", "kind": "app", "icon": "fa5_chart_line" } ] ] }, { "title": "Resolution path", "cells": [ [ { "label": "p99 ≤ 3 ms in-process", "kind": "app", "icon": "fa5_bolt" } ], [ { "label": "staleness metric rising", "kind": "app", "icon": "fa5_hourglass_half" } ], [ { "label": "never fails: serves stale", "kind": "app", "icon": "fa5_check_circle" } ], [ { "label": "alert at 15 min stale", "kind": "platform", "icon": "fa5_bell" } ] ] } ], "note": "Every row gives up freshness, fidelity or the ability to change. Only the trust row gives up availability, and it does so deliberately.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "17-deployment-architecture", "title": "Deployment Architecture", "layout": "nested", "canvas": { "width": 1750 }, "boxes": [ { "title": "Primary data centre", "kind": "onprem", "dir": "col", "children": [ { "title": "Platform cluster — Kubernetes", "kind": "boundary", "nodes": [ { "id": "api", "label": "Config API", "sub": "3 replicas", "kind": "app", "icon": "fa5_plug" }, { "id": "bctl", "label": "Build controller", "sub": "Argo Workflows", "kind": "app", "icon": "argocd" }, { "id": "rel", "label": "Release controllers", "sub": "leader-elected", "kind": "app", "icon": "fa5_map_signs" }, { "id": "pg", "label": "PostgreSQL", "sub": "Patroni, 3 nodes", "kind": "store", "icon": "postgresql" } ] }, { "title": "Distribution tier — the only tier the fleet touches", "kind": "trust", "nodes": [ { "id": "etcd", "label": "etcd", "sub": "3-node quorum", "kind": "store", "icon": "fa5_map_signs" }, { "id": "oci", "label": "OCI registry", "sub": "2 replicas", "kind": "store", "icon": "fa5_box" }, { "id": "minio", "label": "MinIO", "sub": "erasure-coded", "kind": "store", "icon": "minio" }, { "id": "nats", "label": "NATS JetStream", "sub": "3-node", "kind": "queue", "icon": "fa5_bullhorn" } ] }, { "title": "Evidence tier", "kind": "boundary", "nodes": [ { "id": "kfk", "label": "Kafka", "sub": "3 brokers", "kind": "queue", "icon": "kafka" }, { "id": "ch", "label": "ClickHouse", "sub": "2 shards × 2", "kind": "store", "icon": "clickhouse" }, { "id": "worm", "label": "Audit WORM", "sub": "Object Lock", "kind": "store", "icon": "fa5_archive" } ] }, { "title": "Shared platform services", "kind": "boundary", "nodes": [ { "id": "kc", "label": "Keycloak", "kind": "security", "icon": "keycloak" }, { "id": "spire", "label": "SPIRE server", "kind": "security", "icon": "fa5_id_badge" }, { "id": "bao", "label": "OpenBao", "sub": "HSM seal", "kind": "security", "icon": "fa5_key" }, { "id": "obs", "label": "Prometheus + Loki", "kind": "platform", "icon": "prometheus" } ] } ] }, { "title": "Application clusters — where resolution actually happens", "kind": "lane", "dir": "row", "children": [ { "title": "Cluster A · ~180 services", "kind": "plain", "nodes": [ { "id": "podA", "label": "AI feature pod", "sub": "SDK + resident bundle", "kind": "app", "icon": "fa5_cube" } ] }, { "title": "Cluster B · ~120 services", "kind": "plain", "nodes": [ { "id": "podB", "label": "AI feature pod", "sub": "SDK + resident bundle", "kind": "app", "icon": "fa5_cube" } ] }, { "title": "Batch & offline", "kind": "plain", "nodes": [ { "id": "job", "label": "Replay job", "sub": "pinned digest", "kind": "app", "icon": "fa5_history" } ] } ] } ], "outside": [ { "id": "dr", "label": "Secondary site", "sub": "read replica of artefacts", "kind": "external", "icon": "fa5_server" }, { "id": "git", "label": "Git remote", "kind": "external", "icon": "git" } ], "edges": [ { "from": "podA", "to": "oci", "label": "pull by digest" } ], "note": "The pointer store's writable primary is single-site in the MVP; the secondary carries an artefact read replica, which is enough to keep the fleet serving. The 30 s poll backstop, the exposure path to Kafka and MinIO's replication are drawn on views 14, 15 and 10.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "18-release-and-rollback-loop", "title": "The Release Loop — and Why Rollback Is Not a Special Case", "layout": "cycle", "centre": { "label": "A behaviour change", "sub": "one digest" }, "rx": 460, "ry": 225, "nodes": [ { "id": "author", "label": "Author", "sub": "text + rationale", "kind": "app", "icon": "fa5_file_alt" }, { "id": "seal", "label": "Build & seal", "sub": "validate, pin, sign", "kind": "security", "icon": "fa5_stamp" }, { "id": "gate", "label": "Gate", "sub": "eval + approval", "kind": "decision", "icon": "fa5_balance_scale" }, { "id": "promote", "label": "Promote", "sub": "pointer write", "kind": "app", "icon": "fa5_map_signs" }, { "id": "rollout", "label": "Roll out", "sub": "percentage or variant", "kind": "app", "icon": "fa5_percentage" }, { "id": "observe", "label": "Observe", "sub": "guardrails + exposures", "kind": "platform", "icon": "fa5_chart_line" }, { "id": "decide", "label": "Keep or revert", "sub": "same mechanism, backwards", "kind": "decision", "icon": "fa5_undo" } ], "ringLabels": [ "draft", "digest", "verdict", "live", "traffic", "signal", "next version" ], "note": "A rollback re-enters at Promote with an older digest. Nothing in this loop is rebuilt to go backwards.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "19-observability", "title": "Observability — Signals by Plane", "layout": "grid", "laneHeaderWidth": 150, "columns": [ "Authoring", "Build", "Release", "Distribution", "Resolution", "Evidence" ], "rows": [ { "title": "Metrics", "cells": [ [ { "label": "review age", "kind": "platform" } ], [ { "label": "gate pass rate", "kind": "platform" } ], [ { "label": "promotions/day", "kind": "platform" } ], [ { "label": "convergence p99", "kind": "platform", "icon": "fa5_project_diagram" } ], [ { "label": "resolve p99", "kind": "platform", "icon": "fa5_bolt" } ], [ { "label": "drop rate", "kind": "platform" } ] ] }, { "title": "Logs", "cells": [ [ { "label": "who edited what", "kind": "platform" } ], [ { "label": "validation fails", "kind": "platform" } ], [ { "label": "gate verdicts", "kind": "platform" } ], [ { "label": "pull, verify, reject", "kind": "platform" } ], [ { "label": "sampled resolves", "kind": "platform" } ], [ { "label": "back-pressure", "kind": "platform" } ] ] }, { "title": "Traces", "cells": [ [], [ { "label": "build span", "kind": "platform", "icon": "jaeger" } ], [ { "label": "promote → notice", "kind": "platform", "icon": "jaeger" } ], [ { "label": "pull → serving", "kind": "platform", "icon": "jaeger" } ], [ { "label": "digest on the span", "kind": "platform", "icon": "fa5_tag" } ], [] ] }, { "title": "Audit", "cells": [ [ { "label": "confidential reads", "kind": "security", "icon": "fa5_eye" } ], [ { "label": "signature issued", "kind": "security", "icon": "fa5_stamp" } ], [ { "label": "promotion, approval", "kind": "security", "icon": "fa5_file_signature" }, { "label": "override, rollback", "kind": "security", "icon": "fa5_undo" } ], [ { "label": "trust bundle change", "kind": "security", "icon": "fa5_shield_alt" } ], [], [ { "label": "evidence export", "kind": "security", "icon": "fa5_archive" } ] ] }, { "title": "Alerts", "cells": [ [], [ { "label": "gate blocked > 24 h", "kind": "risk", "icon": "fa5_bell" } ], [ { "label": "guardrail breach", "kind": "risk", "icon": "fa5_exclamation_triangle" } ], [ { "label": "not 100% at 60 s", "kind": "risk", "icon": "fa5_bell" }, { "label": "signature rejected", "kind": "risk", "icon": "fa5_ban" } ], [ { "label": "staleness > 15 min", "kind": "risk", "icon": "fa5_hourglass_half" } ], [ { "label": "drop rate > 1%", "kind": "risk", "icon": "fa5_bell" } ] ] } ], "note": "Two empty cells in Traces are deliberate: authoring is human-paced and evidence is a stream, neither has a span worth keeping.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "20-security-trust-zones", "title": "Security — Trust Zones and What Crosses Them", "layout": "zones", "zones": [ { "title": "Corporate network — humans", "kind": "trust", "nodes": [ { "id": "pe", "label": "Prompt engineer", "kind": "actor" }, { "id": "oncall", "label": "On-call engineer", "kind": "actor" }, { "id": "console", "label": "Registry Console", "kind": "app", "icon": "react" } ] }, { "title": "Control plane — authenticated, authorised per key namespace", "kind": "trust", "nodes": [ { "id": "api", "label": "Config API", "kind": "integration", "icon": "fa5_plug" }, { "id": "gate", "label": "Gate engine", "kind": "decision", "icon": "fa5_balance_scale" }, { "id": "pg", "label": "Authoring store", "kind": "store", "icon": "postgresql" }, { "id": "kc", "label": "Keycloak", "kind": "security", "icon": "keycloak" } ] }, { "title": "Key custody — no human read path", "kind": "trust", "nodes": [ { "id": "bao", "label": "OpenBao transit", "sub": "HSM seal", "kind": "security", "icon": "fa5_key" }, { "id": "sign", "label": "Signer", "sub": "sign-only role", "kind": "security", "icon": "fa5_stamp" }, { "id": "trust", "label": "Trust bundle", "sub": "published, versioned", "kind": "security", "icon": "fa5_certificate" } ] }, { "title": "Distribution — read-only, unauthenticated read of signed content", "kind": "trust", "nodes": [ { "id": "oci", "label": "Artefact registry", "kind": "store", "icon": "fa5_box" }, { "id": "etcd", "label": "Pointer store", "kind": "store", "icon": "fa5_map_signs" }, { "id": "nats", "label": "Change bus", "kind": "queue", "icon": "fa5_bullhorn" } ] }, { "title": "Application runtime — workload identity only", "kind": "trust", "nodes": [ { "id": "pod", "label": "AI feature pod", "kind": "app", "icon": "fa5_cube" }, { "id": "sdk", "label": "Resolver SDK", "kind": "app", "icon": "fa5_shield_alt" }, { "id": "spire", "label": "SPIRE agent", "kind": "security", "icon": "fa5_id_badge" } ] }, { "title": "Evidence — write-once, readable, never mutable", "kind": "trust", "nodes": [ { "id": "worm", "label": "Audit ledger", "sub": "hash-chained", "kind": "store", "icon": "fa5_archive" }, { "id": "ch", "label": "Exposure store", "sub": "redacted for confidential keys", "kind": "store", "icon": "clickhouse" } ] } ], "edges": [ { "from": "console", "to": "api", "label": "OIDC over mTLS" }, { "from": "gate", "to": "sign", "label": "sign this digest" }, { "from": "sign", "to": "oci", "label": "signed bundle only" }, { "from": "pod", "to": "oci", "label": "SVID read" }, { "from": "sdk", "to": "trust", "label": "verify against bundle" }, { "from": "api", "to": "worm", "label": "append-only", "kind": "async" }, { "from": "pod", "to": "ch", "label": "exposure, no prompt text", "kind": "async" } ], "note": "No arrow runs from the application runtime into the control plane. A compromised app pod can read signed artefacts and nothing else.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } }, { "id": "21-identity-and-signing", "title": "Identity and Signing — Who Proves What, In What Order", "layout": "sequence", "lifelines": [ { "id": "pe", "label": "Prompt engineer", "kind": "actor" }, { "id": "kc", "label": "Keycloak", "kind": "security" }, { "id": "api", "label": "Config API", "kind": "integration" }, { "id": "bao", "label": "OpenBao", "kind": "security" }, { "id": "oci", "label": "Artefact registry", "kind": "store" }, { "id": "spire", "label": "SPIRE", "kind": "security" }, { "id": "sdk", "label": "Resolver SDK", "kind": "app" } ], "messages": [ { "from": "pe", "to": "kc", "label": "OIDC login", "kind": "call" }, { "from": "kc", "to": "pe", "label": "token + group claims", "kind": "return" }, { "from": "pe", "to": "api", "label": "promote(key, digest)", "kind": "call" }, { "from": "api", "to": "api", "label": "authorise: promote on namespace", "kind": "self" }, { "from": "api", "to": "pe", "label": "refused: author ≠ approver", "kind": "error" }, { "from": "api", "to": "bao", "label": "sign digest (sign-only role)", "kind": "call" }, { "from": "bao", "to": "api", "label": "signature", "kind": "return" }, { "from": "api", "to": "oci", "label": "push bundle + signature", "kind": "call" }, { "from": "sdk", "to": "spire", "label": "fetch SVID", "kind": "call" }, { "from": "spire", "to": "sdk", "label": "short-lived identity", "kind": "return" }, { "from": "sdk", "to": "oci", "label": "pull by digest (mTLS)", "kind": "call" }, { "from": "sdk", "to": "sdk", "label": "verify against trust bundle", "kind": "self" }, { "from": "sdk", "to": "sdk", "label": "unknown key → reject, keep previous", "kind": "error" } ], "note": "The signing key is never held by the service that authors content, and never by the fleet that consumes it.", "meta": { "v": "1.0", "owner": "Platform Architecture", "d": "2026-09" } } ]