Skip to content

Architecture

Status: Canonical Parent index: Engineering-Standard/README.md, Engineering-Standard/governance/canonical-index.md

Scope

This directory holds platform and system architecture: the object model, contracts, projections, receipts, domain/upstream architecture, infrastructure state, the Gas City spec, the Oracle runtime architecture, and the definitional agent standard.

It does not hold:

  • Operational runbooks — those live in ../operating-model/ and ../infrastructure/
  • Normative doctrine/standards (Drupal, DDEV, Git, evidence contracts) — those live in ../standards/
  • Governance policy, constitution, repository classification — those live in ../governance/
  • ADRs — those live in ../decision-records/

If a document is prescriptive ("MUST", "REQUIRED", "Refuse install when...") it belongs in standards/, not here. If it describes what the platform is and how its parts relate, it belongs here.

Numbering convention

There is no single deliberate 01→15 reading order across this directory. The numbers are two independent, real sub-sequences plus a small number of standalone files that were never part of either:

  • 01–04 — the Platform Compiler tetralogy. Each file self-declares Document N of 4 with an explicit Depends on / Required by chain (Core Object Model → Contract Model → Projection Model → Receipt & Provenance Model). This is a deliberate reading order, and it is referenced externally by exact filename (authority-contract.md, capability-contract.md, what-is-an-ai-agent.md, the knowledge map). Read in order.
  • 06a/06b/06c — the infrastructure state triad. Current → Target → Migration, cross-linked to each other and referenced externally by exact filename (e.g. the ADR reference-path audit cites oracle-architecture.md). Read in order.
  • upstream-architecture-model.md carries a number but is not part of either sequence above and nothing fills 05, 07–10, 12–14. Do not invent placeholder files to fill those gaps — they were never assigned, not accidentally skipped.
  • 11-domain-model.md used to be the third orphaned number in this scheme. It was a pre-scaffolding planning draft that self-declared itself historical and superseded by 01/04, was not referenced from anywhere else in the repository, and — once checked against the now-complete 01–04 — every remaining unverified section (object relationships, identity format, projection rules) was confirmed either duplicated or in direct contradiction with the canonical model (e.g. its identity format is <domain>.<type>.<name>, the reverse of 01's <type>.<domain>.<name>). Deleted 2026-09-13; nothing links to it.

New architecture documents should not default to the next free number. Only add a number if the document is genuinely joining 01–04 or 06a–06c as a dependency-ordered member; otherwise give it a plain descriptive filename, as control-plane.md, gas-city-master-spec.md, oracle-architecture.md, and what-is-an-ai-agent.md already do.

Contents

File What it defines
core-object-model.md First-class Platform Compiler objects — Authority, Capability, Contract, Provider, Runtime, Platform, Deployment, Tunnel, Projection, Receipt — and their relationships
contract-model.md Contract structure, the schema/instance/provider/generated directory split, contract types, versioning, retiring ai.json
projection-model.md Compiler pipeline (Readers → Normalizers → Object Graph → Planners → Generators → Emitters → Receipts), projection types, renderers, generated-repo ownership
receipt-provenance-model.md Receipts as immutable business objects — sole authority for receipt schema, types, bounded authority, lineage, storage in Beads → Dolt
oracle-architecture.md Oracle canonical architecture — current state, target state, migration plan, dedicated block storage, on-demand rig provisioning, and lifecycle compaction (consolidated from 06a/06b/06c)
upstream-architecture-model.md Evidence-backed catalog of upstream dependencies (Gas City primitives, dashboard, orders, doctor, KAgent, OpenClaw) — dated snapshot; current docs.gascity.com wins on disagreement
control-plane.md Client-projection architecture — Drupal AMCS/ContextControl.ai connected-client plane, Identity/Model/Knowledge/Capability/Operator/Runtime planes
gas-city-master-spec.md Master Spec — Gas City primitives, $GC_HOME vs /.gc, split storage classes, worktree auto-pruning, connected clients, customer pack packaging
what-is-an-ai-agent.md Definitional standard — descriptive definition of "agent", Bluefly admission standard, implementation profile (OSSA/DUADP/DID/Cedar/Gas City), evidence status
drupal-factory-master-plan.md Factory Master Plan — IN-PROGRESS architecture audit for blueflyio/agent-platform/drupal.

Subdirectories

  • ddev/ — ddev-architecture.md (Bluefly's DDEV distribution model: ownership stack, plane separation, thin-adapter rule) and addon-playlists.md (the playlist/admission-rule matrix). Both cross-link to the normative standards/drupal/ddev/ddev-standard.md, standards/drupal/ddev/ddev-addon-policy.md, and standards/drupal/ddev/ddev-playlist-standard.md — those are the "MUST" rules; these two are the "why". Kept separate deliberately; do not merge without also resolving the apparent overlap between the three standards/drupal/ddev/ddev-*.md files themselves, which is out of scope for this directory.
  • gascity/ — blucity-packs-map.md only (Gas City packs → product/monetization matrix). A same-named gas-city-master-spec.md redirect stub was removed 2026-09-13: it was a leftover from the 2026-09-09 dedupe pass (16cc8e42) that already established ../gas-city-master-spec.md as canonical; nothing linked to the stub.