AI Software Factory Reference Architecture
Connect intent, authority, execution, verification, delivery, operations, and learning through one canonical architecture.
A focused view of boundaries, contracts, state, authority, failure paths, and tradeoffs drawn from this chapter.
Reconstruct and defend this chapter’s architecture.
Reconstruct the architecture, name each boundary, and defend the tradeoffs.
Open the source exercise
Draw all planes and the golden path in ten minutes. For every arrow state the command/event, identity, authoritative record, failure mode, idempotency strategy, and human decision. Then redraw it as a three-deployment V1 and defend what you combined.
3.3 Deployment and trust-boundary view
The diagram is a scale-out option, not a service mandate. A V1 may combine API, orchestrator, policy, and records in a modular deployment. It must still use authenticated interfaces, separate worker and validator contexts, scoped credentials, explicit egress, immutable subject versions, and durable state.
Trust changes at channel-to-API, control-to-worker, sandbox-to-gateway, retrieval-to-context, producer-to-validator, evidence-to-decision, and delivery-to-production boundaries. Each crossing authenticates both sides, authorizes the exact action, validates schema and classification, limits tenancy and destination, and records a correlation key.
3.4 Authority and evidence view
| Record | Produced by | Authorizes or proves | Must bind |
|---|---|---|---|
| Intent decision | Named business authority | Why work may begin | Purpose, outcome, constraints, owner |
| Policy decision | Policy service under delegated governance | Whether a requested action is eligible | Actor, subject, action, resource, context, policy version |
| Grant | Credential or grant service | Narrow runtime authority | Recipient identity, scope, purpose, expiry, revocation |
| Work order and manifest | Control plane | Frozen execution request | Plan, capabilities, context policy, budgets, quality contract |
| Attempt | Orchestrator and worker | What execution occurred | Manifest, worker, environment, lease, tool calls, artifacts |
| Evaluator result | Independent quality context | One measured claim | Subject digest, evaluator version, dataset, result, uncertainty |
| Proof package | Evidence service | Eligibility for a named decision | All required evidence, contradictions, expiry, lineage |
| Human decision | Named decision owner | Approval, rejection, restriction, exception, or acceptance | Exact subject, evidence, reason, conditions, expiry |
| Release record | Delivery system | What entered an environment | Artifact, configuration, migration, target, rollout, rollback |
| Outcome assessment | Operations and business owner | Whether value and safety held in reality | Release, observation window, SLOs, business outcome, incidents |
| Learning decision | Change owner | Whether a configuration change may be promoted | Baseline, candidate, evaluation, risk, approval, rollback |
Decision lineage is a graph of observable records. It intentionally excludes private chain-of-thought. Reproducibility comes from exact inputs, versions, actions, outputs, policy decisions, and evidence.
3.5 Boundary contract
Every material arrow in any view must define:
| Field | Requirement |
|---|---|
| Direction | Command requests a state change; event reports an accepted fact |
| Identity | Authenticated caller, workload, recipient, and delegated authority |
| Schema | Versioned payload with classification and tenant |
| Authority | Owning policy decision and permitted subject/action/resource |
| State | Expected version, preconditions, valid next states, authoritative store |
| Delivery | Idempotency key, deduplication, acknowledgement, deadline |
| Failure | Timeout, retry class, backoff, circuit break, compensation, escalation |
| Evidence | Correlation, input/output digest, audit event, proof eligibility |
| Human decision | Named gate, options, required evidence, expiry and exception path |
| Compatibility | Producer/consumer support window, deprecation, revocation |
Retries are safe only when the operation is idempotent or a reconciliation protocol can determine the external result. A timeout creates uncertainty; it does not prove failure. Critical boundaries fail closed when authority cannot be established and degrade explicitly when a safe read-only path exists.
3.6 Failure trace
For a compromised capability: registry revocation blocks new resolutions; the control plane identifies affected manifests and pauses work; grant and tool gateways revoke authority; workers checkpoint and stop; evidence derived from the version becomes ineligible; delivery blocks affected artifacts; incident response preserves state; recovered work resolves a qualified replacement, re-executes required checks, and requires a new decision. No single log or dashboard substitutes for this state reconciliation.
4. Tradeoffs
Plane separation improves reasoning and security but adds contracts and operational overhead. A modular monolith is often the right V1: one deployment, explicit modules, separate identities for external execution, and stable events. Microservices should follow demonstrated scale or isolation needs, not the diagram.
Multi-agent orchestration is a capability, not a mandatory topology. A single executor is preferable when specialization adds coordination cost without independent assurance.
5. Current Mission Control Implementation
Mission Control’s React UI and Convex functions form much of the control/data plane. The Hono orchestration server, executor adapters, worktrees, GitHub App integration, leases, run events, and artifacts form an emerging execution plane. QC runs, verification receipts, approval decisions, GitHub checks, and release-gate automation form an incomplete quality/delivery plane. Identity, permissions, governance policy, and sandbox controls supply parts of the security plane.
The boundaries are not equally mature. convex/qcRuns.ts still invokes mock adapters and contains a policy TODO; convex/governance/releaseGateAutomation.ts operates in SHADOW; PR publication and remote sandbox controls live on study branches rather than the cited main baseline; and the browser-operated Mission-to-validated-PR path remains the decisive proof gap.
Curriculum maturity is not implementation proof.
This chapter defines architecture or practice. It does not by itself prove a corresponding production implementation.
Review this chapter.
Challenge a claim, boundary, missing failure mode, unclear term, or unsupported evidence statement.
- Claim
- Boundary
- Failure
- Evidence