02 — Architecture
Boundariesbefore features.
Not a chain of prompts and not a monolithic migration script. An event-driven control plane with independently deployed capabilities, a separately executed data plane, durable state, deterministic governance and explicit failure recovery.
A.01System flow
Interpretation flows down. Authority never flows up.
LEGACY ESTATE → GOVERNED AGENT FLEET → CLOUD DATA PLANE → BIGQUERY
Hover a node to trace its path
A.02Planes
Three planes, three different kinds of truth.
- I
Control plane
Agents reason about metadata, risk, plans and evidence.
The orchestrator advances a run through legal states and resolves approved providers by capability. AgentCards are versioned, signed and pinned to each run. Firestore stores durable run state and idempotency claims. Pub/Sub delivers stage events with dead-letter handling.
- Orchestrator
- Agent Registry
- Policy engine
- Durable state
- Idempotent messaging
- Cross-run memory
- II
Data plane
Managed jobs move rows; deterministic validators compare source and target.
Cloud Run Jobs execute bounded table movement. In the measured path, three jobs loaded customers, orders and tags from Cloud SQL for PostgreSQL into BigQuery. The executor reports row counts, byte counts, duration and completion evidence independently of the agent control plane.
- Cloud Run Jobs
- Cloud SQL for PostgreSQL
- Cloud Storage staging
- BigQuery
- Deterministic validators
- III
Human plane
An authorized operator approves a token cryptographically bound to the plan.
A run cannot reach approval until every required deterministic validation passes. The approval service checks the human identity, verifies separation of duties, and binds the token to the migration plan hash. The Cutover agent can consume a valid token but cannot issue one.
- Firebase Authentication
- Estate-scoped roles
- Separation of duties
- Plan-hash binding
- Append-only decisions
Current execution boundary — The nine-service Cloud Run topology is deployed. Cutover executes as an independent service and the migration data plane runs as independent Cloud Run Jobs. Most pre-migration AgentCards still dispatch locally inside the orchestrator; typed remote dispatch for every remaining stage is the next distribution milestone.
A.03Controls
Six controls the model cannot reach around.
- 01
Policy decisions operate on structured identity and resource inputs, never free-text estate content.
- 02
Estate documents contain secret references, not credential values; runtime resolution is redacted in logs.
- 03
Cloud Run and Pub/Sub use service identities and OIDC; operator roles are scoped by estate.
- 04
Agent publication and approval use separate identities.
- 05
Production cutover requires a human token bound to the exact plan hash.
- 06
BigQuery queries are dry-run first, reserve estimated bytes against a run budget, and enforce maximum bytes billed.
A.04Diagram pack
Thirteen views of the deployed topology.
Every diagram is a hand-built vector rendering of the implemented distributed production topology, checked against the live Google Cloud inventory.
- 01
Whole application and Google Cloud deployment
What is deployed, and where are the trust boundaries?
Click to enlarge
- 02
Agent fleet and capability dispatch
How does work reach an agent, and who is allowed to decide?
Click to enlarge
- 03
Orchestrator state machine
What are the legal run states, and how does failure recover?
Click to enlarge
- 03b
Orchestrator event routes
Which event lands on which handler?
Click to enlarge
- 04
Discovery agent
Where do source facts come from, and what may the model touch?
Click to enlarge
- 05
Lineage agent
Which dependencies are proven, and which are only proposed?
Click to enlarge
- 06
Risk and compliance agent
How is a policy outcome decided?
Click to enlarge
- 07
Migration planner agent
What defines executable scope and wave order?
Click to enlarge
- 08
Validation and reconciliation agent
What makes a run PASS, and what blocks it?
Click to enlarge
- 09
Cutover agent
Who can authorise a cutover, and against what?
Click to enlarge
- 10
Finance impact agent
How is cost measured, and what happens when it cannot be?
Click to enlarge
- 11
Reliability, idempotency and dead letters
How does at-least-once delivery stay safe?
Click to enlarge
- 12
WWI flagship migration sequence
What actually happened in the retained acceptance run?
Click to enlarge
Next
The stack
Technology