ARCHITECTURE.md
Agent system architecture
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.
Fillable structure
Replace prompts with project evidence.
Remove any field that does not apply. A smaller maintained file is more useful than generic documentation that agents and reviewers cannot trust.
- 01
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
- 02
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
- 03
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
- 04
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 field guides
Next template
DESIGN.md · Agent product design