Guide
Architecture diagrams that stay current
An architecture diagram shows what a system is made of and how the parts connect. Every team has some; almost every team's are out of date. The fix isn't discipline — it's moving the diagram into the same workflow as the code it describes, so it changes when the architecture changes and CI notices when it doesn't.
The architecture diagrams worth maintaining
- System context — your system in the middle, users and external systems around it. The one diagram everyone from support to the CTO can read. (This is level one of the C4 model.)
- Container / component — the deployable parts and their responsibilities. The software architecture diagram engineers actually use day to day.
- Architecture map — capabilities grouped by domain, with status (target, gap, deprecated). The system design diagram for planning conversations.
- Flows and data — a sequence diagram per critical path and an ERD for the schema.
An architecture diagram as code
In Chiltepin, an architecture diagram is a typed YAML block inside a Markdown document. This is the archmap starter template and its real rendered output — the exact SVG chiltepin build produces:
```archmap
title: Target platform architecture
cols: 3
areas:
- label: Customer channels
accent: blue
items:
- Web storefront
- { name: Mobile app, status: target }
- label: Commerce
accent: teal
items:
- Catalog
- Checkout
- { name: Promotions, status: gap }
- label: Platform services
accent: purple
desc: Shared capabilities every domain builds on.
items:
- Identity
- { name: Event bus, status: new }
- { name: Legacy ESB, status: deprecated }
```Because the diagram is structured text with a schema, chiltepin check validates it like code — unknown fields, dangling references, and malformed entries fail CI instead of shipping. The diagram lives in git, changes in pull requests, and diffs like everything else in the repository. That's the docs-as-code approach applied to architecture.
Generating architecture diagrams with AI
The fastest way to produce these diagrams is to not draw them: your AI agent already reads the codebase, so let it write the blocks. npx skills add jdiejim/chiltepin -g teaches your agent the grammar once — Claude Code, Cursor, Codex, Copilot and 70+ others; then "draw the system context for the payments service" is a prompt, and the result is a validated, reviewable diff — not a screenshot. More on that workflow on the AI diagram generator page.
Diagrams are half the document
An architecture diagram rarely stands alone — it belongs inside a design doc, a service overview, or an ADR. Chiltepin renders the whole document from one Markdown source: a growing library of typed blocks including 25+ diagram types, exported as a static website, slides, or PDF. Start from the system-design template and the structure is already there.
Frequently asked questions
- What is an architecture diagram?
- An architecture diagram is a visual model of a software system: the parts it is made of (services, databases, external systems), how they connect, and where the boundaries are. Good ones answer a specific question for a specific audience — a context diagram for stakeholders, a container diagram for engineers, a deployment diagram for operations.
- What types of architecture diagram should a team maintain?
- Most teams need four: a system context diagram (the system and its neighbors), a container or component diagram (the deployable parts and their responsibilities — the C4 model formalizes these levels), a data-flow or sequence diagram for the critical paths, and an ERD for the data model. Anything beyond that should exist only if someone asks the question it answers.
- How do I create a system architecture diagram?
- Start from the audience and the question, not the boxes: who reads this, and what decision does it support? Then name the system, its users, and its external dependencies; add the internal parts at one consistent level of zoom; and label every arrow with what actually flows across it. Keeping it as text in your repository — rather than a drawing-tool canvas — is what keeps it reviewable and current.
- Why do architecture diagrams always go stale?
- Because they usually live outside the engineering workflow — a drawing-tool canvas or a wiki image that no code review touches and no CI check validates. A diagram defined as code in the repository changes in the same pull request as the architecture change, and a schema validator can fail the build when it references things that no longer exist.
- Can AI generate architecture diagrams?
- Yes, and it works best when the output is structured text rather than an image. An AI agent that can read your repository can write the architecture map or C4 diagram as typed YAML, chiltepin check validates the structure, and you review a diff. Image-generating tools produce pictures that cannot be validated, diffed, or edited.