Architecture Overview
Agent Prompt Snippet
Ensure the project has an architecture overview describing major components, their responsibilities, communication patterns, and deployment topology.Purpose
An architecture overview is the highest-level technical map of a system. It names the major components, explains what each one is responsible for, shows how they communicate, and describes how the whole thing is deployed. It is the document a new engineer reads on day one to understand what they are working with—and the document an on-call engineer consults at 2am to understand what broke and why.
The architecture overview is deliberately not exhaustive. It does not enumerate every module, every API endpoint, or every configuration file. It answers three questions: What are the pieces? What does each piece do? How do they talk to each other? Everything else is implementation detail, documented elsewhere.
What makes this document especially valuable is its stability. Implementation details change constantly; the major components of a system change slowly. A well-maintained architecture overview needs updating when something structurally significant happens—a new service is added, a data store is replaced, a synchronous call becomes asynchronous—not every sprint.
For cloud-native and distributed systems, the architecture overview must include a deployment topology diagram showing where components run (Lambda, container, edge, client) and which network boundaries they cross. This is the information missing from most codebases that causes the most confusion during incidents.
Who needs this document
| Persona | Why they need it | How they use it |
|---|---|---|
| Sam (Indie Dev) | Keeps the mental model explicit as the project grows; future Sam will thank present Sam | Draws it before writing code; updates it when adding a major new component |
| Claude Code (AI Agent) | Cannot safely propose refactors or new integrations without knowing the system shape | Reads architecture overview before any structural code change; uses component names as vocabulary |
| Priya (Eng Lead) | Onboards engineers, aligns cross-team discussions, feeds incident postmortems | Links from README; uses during design reviews to identify where a proposed change fits |
| DevOps (CI Operator) | Needs topology to write correct deployment configs, health checks, and runbooks | References during infrastructure changes; verifies topology diagram matches actual deployment |
What separates a good version from a bad one
Criterion 1: Components are named and bounded
✓ Strong: “The system has four top-level components: (1) the API Gateway (entry point for all external traffic, handles auth), (2) the Job Service (processes background tasks from SQS), (3) the PostgreSQL database (source of truth for all persistent state), and (4) the CDN-backed static asset host (serves the React frontend). All components communicate via HTTPS except the Job Service, which reads from SQS.”
✗ Weak: “The system consists of a backend and a frontend. The backend has several services.” (Unnamed components with no boundaries make every subsequent engineering decision harder to reason about.)
Criterion 2: Communication patterns are specified, not implied
✓ Strong: “The API Gateway calls the User Service synchronously (REST over HTTPS, p99 < 50ms target). The User Service publishes domain events to SNS; the Notification Service subscribes asynchronously. There are no direct database queries from the API Gateway—it only reads from the User Service API.”
✗ Weak: “Services communicate with each other as needed.” (Omitting protocol, synchrony, and direction makes it impossible to reason about failure modes or latency budgets.)
Criterion 3: The diagram matches the running system
✓ Strong: Diagram has a date and version. The PR that added the Kafka cluster includes an update to the diagram. The README links to the diagram file in the repo, not a screenshot stored in Confluence.
✗ Weak: The diagram in the wiki was last updated 14 months ago. It shows a Redis cache that was replaced by Elasticache 8 months ago and doesn’t show the new webhooks service.
Criterion 4: Deployment topology is visible
✓ Strong: “API Gateway runs as AWS Lambda (arm64, us-east-1 + us-west-2). Job Service runs as ECS Fargate (single region). Database is RDS PostgreSQL Multi-AZ. Static assets served from CloudFront. Lambda and ECS communicate through a private VPC; RDS is not internet-accessible.”
✗ Weak: “Everything runs in AWS.” (No region, no compute type, no network boundary information—unusable for incident response or cost estimation.)
Common mistakes
Scope creep into implementation details. An architecture overview that enumerates every microservice endpoint or every database table has become a different document. If it’s more than 4 pages including diagrams, it’s trying to be too much. Split implementation detail into the Technical Design Document.
Using the architecture overview as a wish list. Mixing “current state” with “planned future state” without clear labeling creates confusion about what is actually deployed. Use [PLANNED: Q3] markers or a separate “Roadmap” section, clearly delineated.
Forgetting clients. Many architecture diagrams show only server-side components. The mobile app, the third-party webhook consumer, and the CLI tool are also parts of the architecture. If something talks to your system, it belongs in the diagram.
No ownership of updates. Without a designated owner and a stated update cadence, the architecture overview drifts stale within months. Establish: who updates it, when (e.g., before any architectural PR merges), and how to tell if it’s current.
How to use this document
When to create it
Write the architecture overview before the first production deployment. For greenfield projects, sketch it during system design, before writing code. For existing systems, write it when onboarding the first new engineer—that pain of explaining the system is exactly the signal that the document is needed.
Who owns it
The tech lead or architect owns the primary diagram and overall accuracy. Any engineer can propose updates via PR. The architecture overview is a living document in the repository, not a static deliverable.
How AI agents should reference it
get_standard_docs(type="cloud_integration", features=[])
→ architecture_overview in documents[]
→ agent reads the overview before proposing code changes to understand system topology
→ agent uses component names from the overview as vocabulary in its suggestions
→ agent flags if a proposed change crosses an undocumented component boundary
The prompt_snippet — “Ensure the project has an architecture overview describing major components, their responsibilities, communication patterns, and deployment topology” — tells the agent to verify the overview exists and to treat its component vocabulary as authoritative.
How it connects to other documents
The architecture overview is the parent of the Technical Design Document (which dives into implementation details), the API Contract (which specifies one interface in the architecture), and the ADR Log (which explains why the architecture evolved as it did). The SLA definition references component availability targets that must align with the architecture’s redundancy topology.
Recommended Reading
- Software Architecture: The Hard Parts by Neal Ford, Mark Richards et al. — Practical patterns for decomposing and documenting distributed systems.
- Designing Data-Intensive Applications by Martin Kleppmann — Essential for documenting data flow and consistency semantics in distributed architectures.
- The C4 Model for Software Architecture by Simon Brown — A lightweight, four-level diagramming approach (Context, Container, Component, Code) well-suited for architecture overviews.