Twenty-Two Architecture Principles

How to read these

Twenty-two principles, numbered P0 to P21. Most began as a list of twenty in the first edition of the atlas. The second edition added three (P0, P11 and P21), rewrote four (P6, P8, P9 and P10), and checked every one against the incidents and the provider documentation.

A principle stated as a slogan is easy to agree with and hard to apply. So each one here comes with its consequences: what it requires directly (first order), what that in turn requires (second order), and where it leads (third order). If you can follow the chain, you can apply the principle to a system it was never written about.

Some are marked heuristic. Those are context-dependent defaults rather than invariants, usually because they trade against cost.

Truth, capability and provider semantics

P0. Every piece of state has a declared source of truth

Everything else is derived. Caches, replicas, indexes, embeddings, summaries and BI extracts each need a freshness SLO and an invalidation path. Deletion, ACL changes and corrections then have to propagate along the lineage edges from source to copy, which makes lineage completeness a compliance dependency: "where is X?" becomes a graph query, and without lineage a deletion can't be proved.

P1. Capabilities before products

Map requirements to capabilities first, with their facet deltas, and choose products second. Provider choice then becomes a set of explicit equivalence-class decisions, each with an exit cost. The catch is that your model of capabilities has to include the semantic facets (consistency, authorization, failure domain, lifecycle, namespace), or it silently treats different things as the same.

P2. Preserve provider semantics

Declare the equivalence class, E1 to E5, with facets, for every mapping. Every abstraction layer (a Terraform module, an internal platform API, a gateway) must either leak non-equivalent features or reject them. A lowest-common-denominator platform loses the provider's unique features; a superset platform leaks them in surprising places. Either way, the platform team owns the mapping as a versioned artefact.

Identity and authorization

P3. Identity is the first dependency

• First order: identity-provider availability bounds the availability of everything that needs a new token. Token lifetime is a resilience parameter. Break-glass access has to bypass the failed path: accounts excluded from Conditional Access, on hardware keys, and monitored.
• Second order: workload identity federation makes the identity provider, the STS and its signing keys Tier-0 for machines too. SCIM lag becomes authorization lag. Agent identities add a third class of principal, whose credential lives on the blueprint. Authorization latency adds up per hop. And dependency loops appear: the identity provider needs DNS, the network and a database, so if it runs on the platform it authorizes, recovering the platform needs the identity it just lost.
• Third order: identity telemetry (sign-in logs, token issuance rates) is a Tier-0 telemetry stream. Changing identity provider is a Type-1 decision, because every federation trust, issuer URL and audience is a hard-coded edge somewhere. And a tenant compromise is a total compromise, so tiered administration and the identities that can grant permissions are the true Tier-0.
• Quantified by: the revocation window.

P4. Authorization lives outside the model, at the resource

• First order: separate the policy decision point (PDP) from the enforcement point (PEP). The model is never the PEP.
• Second order: identity has to propagate through every hop, on-behalf-of or as-self and always audience-bound, because pass-through creates confused deputies. Claims freshness matters. Enforcement points multiply: retrieval (pre-filter and post-verify), each tool call and each handle, the data layer through row-level security, and approval of side effects. Policy needs versioning and rollback, just like configuration.
• Third order: authorization during a provider failure needs a declared fail mode. Consistency between layers becomes a correctness property, because during a sync the index can say "allowed" while the source says "revoked". And audit has to record which policy version made each decision.
• For MCP specifically: with a stateless protocol, handle ownership is checked on every call. A wrong cacheScope on a list result can leak a per-user tool list through a shared intermediary. Clients must bind credentials to the authorization server that issued them.

P5. Least privilege, bounded blast radius

Use the smallest useful account, project, blueprint and credential scope. That means many narrowly scoped identities, so the identity count explodes, so lifecycle automation (SCIM, deprovisioning, a named sponsor) becomes mandatory. Unused-permission analysis and access reviews become continuous operations. Without them, least privilege quietly decays into "least privilege at the time it was created". Heuristic.

P6. Explicit trust boundaries; derived data inherits

Every hop declares its zone, its residency and its classification. Derived storage inherits the highest classification of its inputs, while exposure can be trimmed per request. Telemetry, prompts, traces and evaluation datasets are derived data too. They inherit residency and classification, which constrains where your observability backends are allowed to live.

Control, configuration and failure

P7. Separate the control plane from the data plane

• First order: pre-provision capacity, so the data plane doesn't need launches or configuration changes to survive.
• Second order: static stability costs idle capacity, about 1.5 times at three zones. And every data-plane dependency on a control-plane API (token introspection, fetching secrets at request time, DNS updates, writes to service discovery) breaks it.
• Third order: you have to test that the data plane survives a control-plane freeze, with "can't change anything" drills.
• Heuristic: static stability is a cost trade, not an invariant.

P8. Configuration is code

Validate configuration against a schema. Validate its size and cardinality. Run the real consumer, including its asynchronous stages. Version the schema, with a skew policy between producers and consumers. Canary it, roll it out in rings, let it bake, and roll it back automatically. Put a feature flag on every new code path that consumes configuration.

• Second order: generated configuration (like Cloudflare's feature file) is configuration whose producer is a query, so a permission change upstream is a configuration change.
• Third order: change management has to trace indirect producers. The boundary of a deployment is the dependency graph, not the repository.
• Stale configuration: consumers must reject or tolerate configuration older than a set age, with the last known good as their fail-static state.

P9. Fail safe deliberately

Every check declares its failure mode from the taxonomy. Protective authorization fails closed, or fails static within the revocation window. Checks that protect availability may fail open, with alarms. Irreversible actions fail to manual. A fail-open path is security-relevant configuration, so it is versioned, alarmed and time-limited.

P10. Failure domains are vectors

Physical, control-plane, configuration, identity, data and supplier. Two components are independent only if they share none of the domains relevant to the kind of fault in question, which is why every design needs a blast-radius analysis.

P11. Recovery state is separate from live and replicated state

• First order: immutable backups.
• Second order: separate credentials, in a backup identity plane. Separate keys, because a KMS key in a compromised account makes the backups unreadable or deletable. A separate backup control plane. An RPO set by backup cadence, not by replication lag. And restore testing.
• Third order: a restore dependency graph, in order: identity, then DNS, then KMS, then the network, then databases, then applications, then rebuilt indexes. Recovery capacity, meaning GPUs and quotas in the disaster-recovery region. Tier-0 restored first. And monitoring of the backups themselves, because a backup that has silently been failing is discovered only during a restore.

P12. Recovery is proven by exercise

Restores, failovers and break-glass access are scheduled tests that produce evidence. Tests carry risk of their own, so they need a safe test architecture, such as isolated restore environments.

P13. Observability is independent of the observed

• First order: a separate failure domain for telemetry, external probes, and status and paging hosted outside the provider.
• Second order: local buffering and local diagnostics. Time synchronisation, because log correlation fails with clock skew. Audit continuity. Telemetry residency, privacy and redaction before storage. Access control on telemetry, because logs contain tokens, prompts and personal data.
• Third order: cardinality and cost management. And a classification to get right: the telemetry pipeline is Tier-0 for incident response, not for serving, so keep it out of the request path.

Evidence, cost and change

P14. Lineage enables deletion and trust

If you can't trace a copy back to its source, you can't delete it on request, and you can't say what an answer was built from.

P15. Evaluate AI like software

Pin the model, prompt, index and tool-schema versions together. Every route through a model router is a separate system under test. Evaluation cost scales with routes multiplied by versions, so route explosion is bounded by the evaluation budget.

P16. Cost is an architectural property

Design unit metrics: cost per request, per task, per user. Meter tokens at the gateway, because FOCUS 1.4 has no token columns. And treat cost anomalies as security signals too, because a runaway agent (ASI08) shows up on the bill before it shows up anywhere else.

P17. Reversibility is measured

For every Type-1 decision, record the exit cost and whether it depends on a provider-unique (E4) feature.

P18. Evidence before certainty

Label claims as fact, inference or open question, with dates and lifecycle status.

P19. Assumptions are visible

Write down the assumption, what would flip it, and the trigger for revisiting the decision.

P20. Automate repeatability

Infrastructure as code and policy as code are the source of truth, and drift is a defect. Consequently, IaC state files and pipelines are Tier-0, because they can recreate or destroy everything, and the CI/CD identity is the most privileged non-human principal you have.

P21. Version everything behind an API; time is a dependency

Models, protocols and tools all sit behind versioned interfaces. Deprecations are scheduled outages. And every TTL, token lifetime, lease and propagation delay is a design parameter with an owner.