# ARCHITECTURE.md

> Describe system boundaries, responsibilities, data and control flow, trust zones, dependencies, failure behavior, and deployment topology so changes can be evaluated against an explicit operating model.

**Decision rule:** Use architecture documentation for durable system structure and cross-cutting constraints. Keep user-facing interaction detail in DESIGN.md and feature-specific implementation choices in PLAN.md.

## How to use this template

- Replace every angle-bracket placeholder with project-specific evidence.
- Remove sections that do not apply instead of leaving ambiguous boilerplate.
- Link decisions to their specifications, tasks, tests, traces, and owners.
- Re-review this file when the workflow, authority boundary, or primary source changes.

## Scope and boundaries

> State what the system owns, what it delegates, and where trust or organizational responsibility changes.

- **System purpose:** <Describe the outcomes and users this architecture supports>
- **In scope:** <List owned capabilities and data>
- **External boundaries:** <List providers, agents, tools, protocols, and teams outside the boundary>

## Components and flows

> Make runtime responsibilities and important state transitions inspectable.

- **Components:** <List each component, owner, responsibility, and interface>
- **Data flow:** <Describe inputs, persisted state, context assembly, outputs, and sensitive data movement>
- **Control flow:** <Describe orchestration, delegation, approvals, retries, and termination>

## Quality attributes and decisions

> Connect architecture choices to measurable constraints instead of framework preference.

- **Targets:** <Record reliability, latency, cost, security, privacy, and scale objectives>
- **Key decisions:** <Link the decision records that justify important tradeoffs>
- **Constraints:** <State provider, compliance, deployment, compatibility, and team constraints>

## Operations and evolution

> Explain how the system fails, recovers, changes, and proves compatibility.

- **Failure modes:** <List dependency, model, tool, data, queue, and authorization failures>
- **Deployment:** <Describe environments, release units, migration order, and rollback>
- **Evolution:** <Define compatibility promises, deprecation, and architecture review triggers>

## Related AgentAtlas field guides

- [Agent architecture](https://agentatlas.dev/topics/architecture)
- [Tools and MCP](https://agentatlas.dev/topics/tools-mcp)
- [Deployment and operations](https://agentatlas.dev/topics/deployment-operations)

## Primary references

- [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) — Composable workflow patterns, the workflow-versus-agent boundary, and the case for starting with simpler architecture.
- [A2A protocol specification](https://a2a-protocol.org/latest/specification/) — Architecture for communication between independently operated agents, including discovery, tasks, messages, artifacts, and security schemes.
- [MCP specification](https://modelcontextprotocol.io/specification/) — The protocol model, capability negotiation, tools, resources, prompts, transports, authorization, and security considerations.
- [Connect Codex to MCP servers](https://learn.chatgpt.com/docs/extend/mcp) — How Codex discovers, configures, authenticates, and uses MCP servers and their capabilities.
- [Running agents](https://openai.github.io/openai-agents-python/running_agents/) — Run execution, limits, state and conversation strategies, streaming, errors, and lifecycle behavior.
- [OpenAI Agents SDK tracing](https://openai.github.io/openai-agents-python/tracing/) — Production workflow tracing, grouping, processors, sensitive data, and operational diagnosis.

---

- Template version: 1.0.0
- Reviewed: 2026-07-26

Generated deterministically from reviewed AgentAtlas records.