Architecture Review Board Packet

This packet is the canonical entry point for reviewing FDAI’s target architecture. It separates approval of the design baseline from approval to deploy or enable production enforcement, and it links every claim to a repository artifact or a fork-supplied evidence binding.

Decision requested: conditionally approve the Azure target-architecture baseline. Production deployment and enforce-mode approval are explicitly out of scope while config/architecture-review.yaml reports production_approval_status: blocked.

Customer boundary: upstream defines the reusable architecture and evidence contract. A fork supplies environment values, accountable people, privacy decisions, service objectives, and production evidence.

Design at a glance

FDAI is an agent-driven, headless control plane with a non-privileged console and GitOps/ChatOps delivery. Fifteen fixed agents own sensing, judgment, arbitration, approval, execution, verification, recovery, audit, and learning through typed pub/sub. The operating ontology is supporting truth and safety infrastructure; it constrains agent interpretation but never grants authority or acts.

Repeatable events use T0 deterministic rules and T1 verified reuse; only residual ambiguity reaches T2 grounded reasoning. Every mutation passes the safety check, carries stop, rollback, impact, audit, and independent effect-verification contracts, and starts in observation mode.

FDAI calls this Outcome-Driven Token Economics: maximize verified operational value while minimizing model calls, tokens, latency, and cost by using ontology-grounded T0/T1 paths by default and reserving direct source retrieval, stronger models, verification, and human approval for residual ambiguity or risk. Accuracy and safety remain hard constraints.

Decision boundary

Decision	Current request	Approval effect
Target architecture	Conditional approval	Accepts the system boundaries, Azure day-zero choices, control loop, and safety model
Production deployment	Not requested	Requires the production evidence gate to pass
Enforce-mode capability	Not requested	Requires per-action observation mode evidence and separate approval
Hyperscale Plan B	Reference only	Becomes applicable only after a measured trigger in the hyperscale design
Sovereign profile	Reference only	Requires a separate regulatory and residency review

The machine-readable decision state lives in config/architecture-review.yaml. Run the structural check on every change:

python3 scripts/governance/check-arb-readiness.py

A production promotion pipeline uses the fail-closed form:

python3 scripts/governance/check-arb-readiness.py --require-production-ready

Scope and context

In scope

• Azure implementation of the headless control plane and its provider boundaries.
• Event Hubs through the Kafka endpoint, Container Apps, PostgreSQL Flexible Server with pgvector, Key Vault references, managed identities, Log Analytics, and Application Insights.
• The T0/T1/T2 control loop, quality gate, unified safety check, executor, audit, GitOps, and human approval.
• Development, staging, and production artifact promotion with observation mode-before-enforce controls.
• Day-zero operations, rollback, observability, cost, and the measured path to cell-based scale.

Out of scope for this decision

• Non-Azure provider implementations.
• Customer-specific rules, thresholds, identities, endpoints, and organization policy.
• Production approval, because owner and evidence bindings remain intentionally empty upstream.
• Plan B deployment, sovereign-profile certification, and secondary-region resources.

Architecture views

View	Design authority	Review focus
System context and layer boundaries	App Shape	humans, Git, ChatOps, console, core, and privileged executor boundaries
Control flow	Architecture	event ingestion, tiering, verification, risk decision, execution, and audit
Module and deployment mapping	Project Structure	ownership boundaries and provider adapters
Azure day-zero deployment	Deploy and Onboard	concrete resource inventory and bootstrap order
Identity and data flows	Security and Identity	trust boundaries, authorization, secrets, and STRIDE threats
Scale transition	Hyperscale Cell Architecture	trigger-based move from one cell to sharded cells

Current, target, and transition states

State	Description	Evidence status
Current upstream	Reusable code, Terraform modules, tests, generic configuration, and design docs; no customer production values	Verifiable in this repository
Day-zero target	One Azure region, one Container Apps cell, Event Hubs Kafka, PostgreSQL + pgvector, Key Vault, scoped managed identity, Log Analytics	Design accepted by ADR-0001; production evidence still required
Production target	Signed image, private or explicitly allow-listed data flows, bound owners, approved objectives, blocking release controls, operational-readiness report	Blocked until the manifest production gate passes
Scale target	Multiple cells, policy-driven fan-in, CQRS audit indexing, and deployment profiles	Deferred until a measured trigger is crossed

Requirements traceability

Requirement	Design response	Verification source
Agent-owned closed loop	one accountable agent owns each observe, decide, plan, execute, verify, recover, and learn transition	pantheon parity, topic ownership, and lifecycle tests
Deterministic-first decisions	T0 exact rules, then T1 reuse, then quality-gated T2	tier tests and frozen scenario set
Contract-conformant accuracy	wrong-target, unauthorized, policy-escape, and unverified-success outcomes remain zero	guard metrics and outcome receipts
Minimum human intervention	evidence recovery, reevaluation, smaller safe plan, no-op, and rollback precede human review	touchpoint metrics and escalation traces
No ungated autonomous mutation	unified safety check and role-bound executor	safety check property tests and audit evidence
Separation of duties	requester, approver, judge, and executor are distinct principals	RBAC configuration and human approval tests
Retry safety	stable idempotency key and per-resource serialization	idempotency and replay tests
Reversibility	rollback contract plus stop condition on each ActionType	rollback rehearsal evidence
Customer isolation	fork-supplied values and dependency injection	generic-scope gates and config validation
Operability	health signals, canary, smoke, alert routing, and runbooks	operational-readiness report
Cost control	scale-to-zero, token budgets, resource budgets, and measured graduation triggers	cost confirmation and capacity evidence

Nonfunctional evidence contract

Targets that depend on a deployment are not universal upstream constants. A production deployment records the approved value, measurement method, result, timestamp, and approver in its evidence binding.

Area	Required production evidence	Pass condition
Availability	control-plane SLO and error budget	approved objective plus measured staging result
Latency	p50/p95/p99 by tier and end-to-end canary	within the fork-approved budget
Capacity	sustained and burst event rate, partition lag, DB saturation, quota headroom	no loss; bounded lag; documented saturation point
Reliability	service-specific RPO/RTO and business-impact analysis	approved numeric objectives
Recovery	isolated restore plus regional failover and failback drill	objectives met with integrity and smoke passing; primary fencing, event recovery, and failback verified
Security	threat review, private/allow-listed data-flow validation, least-privilege probe	no unresolved critical/high detected issue
Privacy	privacy impact assessment and data inventory	approved by the privacy owner
Operations	signed operational-readiness report, canary, smoke, alert, and runbook evidence	all production checks pass
Supply chain	SBOM, signature, provenance, vulnerability and IaC scans	release artifact verified; blocking scans clean
Cost	current calculator export, monthly cap, quota, and 12/36-month assumptions	cost owner approval

Data, privacy, and compliance

Data Governance defines the classification, minimization, residency, retention, legal-hold, deletion, model-provider, and privacy-assessment contract. The upstream design does not claim a customer compliance certification. A deployment owner selects its control profile, maps controls to evidence, records exceptions, and binds a privacy and data owner.

Ownership and support

The production gate requires these accountable slots. A group may fill a slot, but every binding must identify an escalation route and a distinct approval authority where separation of duties applies.

Owner slot	Final owner for
architecture-owner	architecture baseline, ADRs, and accepted technical debt
security-owner	threat model, identity, network posture, and security exceptions
privacy-owner	privacy impact assessment and data-processing decisions
data-owner	classification, retention, legal hold, deletion, and data quality
operations-owner	on-call, alerts, runbooks, and operational-readiness acceptance
reliability-owner	SLO, RPO/RTO, recovery design, and drill acceptance
release-owner	artifact provenance, deployment, rollback, and promotion gates
cost-owner	budget, quota, price confirmation, and capacity graduation

Agent operational ownership remains a separate accountability overlay. It does not grant authorization or replace these production owner slots.

Each owner_bindings entry uses this shape:

architecture-owner:
   subject: group:<fork-owned-subject>
   escalation: <fork-owned-escalation-route>

Each evidence_bindings entry is immutable evidence metadata, not the evidence body:

production-terraform-plan:
   uri: evidence://<governed-store-reference>
   sha256: <64-lowercase-hex-digest>
   approved_by: group:<fork-owned-approver>
   approved_at: 2026-07-13T00:00:00Z
   expires_at: 2027-01-13T00:00:00Z

The checker rejects unknown binding keys, missing fields, malformed digests, and invalid timestamps. expires_at must be later than approved_at; an expired binding blocks production readiness. Customer names, resource ids, and evidence bodies remain in the fork’s governed store.

The upstream required-evidence keys cover all Azure Well-Architected Reliability RE:01-10 and Operational Excellence OE:01-11 Best Practice requirements. The checklist evaluator applies each control’s shorter freshness window when one is declared. Binding expiry is the outer validity ceiling and never extends a control-specific freshness window.

Dependencies and failure behavior

Dependency	Contract	Failure behavior	Production evidence
Event Hubs Kafka	ordered, at-least-once event log with DLQ topics	backpressure or hold for review; never drop silently	round-trip, lag, replay, and DLQ test
PostgreSQL + pgvector	transactional state, audit projection, and T1 vectors	fail closed; no in-memory fallback in production	connection, backup, restore, and saturation test
Key Vault reference	environment-secret injection	startup fails if a required secret cannot resolve	rotation and unavailable-vault test
Entra and managed identity	short-lived, audience-scoped identity	deny access; no credential fallback	least-privilege and recertification evidence
Git host	reviewed fix and governance changes	queue proposal; do not execute out of band	protected-branch and rollback test
human approval channel	authenticated, action-bound approval	queue and use configured fallback; timeout is no-op	primary/fallback and replay-resistance test
Model providers	budgeted, grounded T2 and narrator access	hold for review when unavailable or unverified	provider, residency, retention, and budget evidence
Observability backend	correlated logs, metrics, traces, and alerts	raise monitor-of-monitor signal	canary and alert delivery result

Decisions

The ADR index is Architecture Decision Records. ADR-0001 records the accepted Azure day-zero platform baseline. Open environment decisions such as numeric RPO/RTO, retention, cost caps, and production owners are fork bindings, not hidden architecture defaults.

Risk, assumptions, issues, and exceptions

The active critical and high risks are machine-readable under blockers in config/architecture-review.yaml.

Type	Rule
Risk	carries severity, accountable owner slot, mitigation, residual risk, and review date
Assumption	identifies the validating evidence and expires when contradicted or measured
Issue	links to the artifact or implementation that closes it
Exception	is scoped, time-bound where required, independently approved, and audited

An accepted risk is not a resolved blocker. The production gate accepts a critical or high item only after its status and evidence are updated through review.

Runtime status and manual review

The published workflow app is available at /workflow-apps/architecture-review. Its selected Process view renders at /processes/{process_id} from the declarative view and report catalogs. A valid manifest with missing production evidence remains structurally healthy while the production gate stays blocked. The Process projection keeps workflow state, review checks, owner and evidence bindings, approvals, and decisions in typed ontology objects.

Contributor can start or resume observation mode review through POST /workflows/run. Owner can request mode=enforce only when architecture-review is in FDAI_WORKFLOW_ENFORCE_ALLOWLIST. ARB is control-only, so enforce persists real approval and decision transitions but never deploys resources or promotes an ActionType.

Implementation status

The reusable ARB contract, fail-closed production gate, workflow, ontology projection, and read-only workflow app are implemented. Production readiness remains blocked because the upstream manifest intentionally has no customer owner or evidence bindings and all critical or high blockers remain open.

Implementation scope

Area	State	Evidence	Notes
Machine-readable review contract and readiness checker	implemented	config/architecture-review.yaml; core/architecture_review/readiness.py; scripts/governance/check-arb-readiness.py; focused readiness tests	Structural health and production readiness are evaluated separately, and malformed, incomplete, unknown, or expired evidence fails closed.
Review workflow, production gate, and ontology projection	implemented	rule-catalog/workflows/architecture-review.yaml; core/architecture_review/projection.py; runtime/control_loop.py; focused projection tests	The control-only workflow records checks, approvals, and decisions without deploying resources or enabling an ActionType.
Declarative operator review surface	implemented	rule-catalog/operator-console/architecture-review.yaml, views/architecture-review.yaml, and reports/architecture-review-process.yaml; focused view and report tests	The published read-only workflow app and Process view expose projected review state through catalog-validated routes.
Production owner bindings, evidence, and approval	in-progress	config/architecture-review.yaml reports production_approval_status: blocked, empty binding maps, and open critical or high blockers	Repository tests prove the gate behavior, not a customer production approval or governed runtime result.

Implementation history

Date	State	Change	Evidence	Remaining
2026-08-13	in-progress	Adopted the implementation ledger, corrected the runtime exposure to the declarative workflow app, and separated reusable ARB implementation from production approval.	Current change: this document pair and the scope evidence above; the focused ARB readiness, projection, view, and report test command passed 19 tests. Earlier provenance was not reconstructed.	Bind production owners and governed evidence, resolve blockers, and record an approved runtime decision.

Remaining work

• Populate every required owner and evidence binding in a customer fork, resolve or formally accept every critical or high blocker, and record a passing python3 scripts/governance/check-arb-readiness.py --require-production-ready result against unexpired governed evidence.
• Record a staging architecture-review Process that passes the production gate, receives the required independent owner approvals, and persists the signed decision and audit receipt without deploying resources or promoting an ActionType.

Production exit procedure

1. Bind every required owner slot in the customer fork.
2. Attach each required evidence artifact and verify that it contains no secret or customer data in the upstream repository.
3. Resolve or formally accept each blocker through the appropriate governance path.
4. Mark production artifacts ready, approve the design review, and set production approval to ready.
5. Run python3 scripts/governance/check-arb-readiness.py --require-production-ready in the promotion job.
6. Record the ARB decision, approvers, conditions, and expiry of any exception in the audit store.

Passing this gate permits a production deployment review. It does not enable any ActionType; each capability still follows its own observation mode-to-enforce promotion gate.

Next steps

To learn about	Read
Accepted platform decisions	Architecture Decision Records
Data and privacy evidence	Data Governance
Deployment inventory	Deploy and Onboard
Operational handoff	Operational Readiness
Machine-readable readiness state	config/architecture-review.yaml