Architecture Diagram Set
A four-diagram starter set based on the C4 approach, plus the conventions that make diagrams readable — including the one that matters most, saying what each arrow means.
No sign-up. No email. Markdown with Mermaid — edit it in anything.
When to use it
Before build, and updated whenever a structural decision changes.
Who fills it in
Solution architect or tech lead.
Works alongside: BRD · Security Checklist
The template
Instruction lines are marked with > — delete them
once the document is filled in.
System: _______________ Version: 0.1 Date: _______________ Owner: _______________
Four diagrams at decreasing zoom. Most teams need the first two; draw the third only for components with real internal structure. Diagrams below use Mermaid — renders in most Markdown tools, and it is text, so it diffs in version control instead of rotting as a stale image.
Conventions — agree these first#
Every arrow must say what it means. An unlabelled arrow is the single most common defect in architecture diagrams: nobody knows whether it means "calls", "sends data to", "depends on", or "sometimes reads from". Label direction and protocol.
| Convention | Rule |
|---|---|
| Arrow direction | Points the way the request travels, not the data |
| Arrow label | Verb + protocol, e.g. "reads via HTTPS/JSON" |
| Boxes | One responsibility each; if you cannot name it in three words, split it |
| Colour | Never the only carrier of meaning — some readers cannot see it |
| Trust boundaries | Drawn explicitly; this is where security review focuses |
| Anything external | Visually distinct from what you control |
1. Context — who uses this and what it talks to#
One page. The diagram you show a stakeholder. No internal detail.
graph TD
U[Customer] -->|uses via browser| S[Your System]
A[Internal Staff] -->|administers| S
S -->|reads/writes via HTTPS| P[Payment Provider]
S -->|sends email via SMTP| E[Email Service]
S -->|queries via JDBC| D[(Core Database)]Actors:
| Actor | Type | What they do |
|---|---|---|
| Person / System |
2. Containers — the deployable parts#
Applications, services, databases, stores. What runs where, and how the parts communicate. This is the diagram engineers use most.
graph TD
subgraph "Trust boundary: our infrastructure"
W[Web Application<br/>static HTML/CSS/JS]
A[API<br/>PHP 8.3]
DB[(Database<br/>MySQL)]
Q[Job Runner<br/>cron]
end
U[Browser] -->|HTTPS| W
W -->|HTTPS/JSON| A
A -->|SQL over local socket| DB
Q -->|SQL| DB
A -->|HTTPS| X[External API]| Container | Technology | Responsibility | Scaling | Data held |
|---|---|---|---|---|
3. Components — inside one container#
Only for containers with genuine internal structure. Skip otherwise.
graph LR
R[Router] --> C[Controller]
C --> S[Service Layer]
S --> Rp[Repository]
Rp --> DB[(Database)]
S --> Ext[External Client]4. Deployment — where it physically runs#
graph TD
subgraph "Host: production VPS"
N[nginx :443]
F[php-fpm pool]
M[(MySQL :3306 localhost only)]
end
I[Internet] -->|TLS 1.3| N
N --> F
F --> M| Environment | Host | Sizing | Notes |
|---|---|---|---|
| Production | |||
| Test |
Data flow and classification#
What moves where, and how sensitive it is. This drives security decisions.
| Data | Classification | From | To | Protection |
|---|---|---|---|---|
| Public / Internal / Confidential / Personal |
Trust boundaries#
| Boundary | What crosses it | Control |
|---|---|---|
| Internet → application | TLS, authentication, rate limit | |
| Application → database | Network isolation, least-privilege account | |
| Application → third party |
Key decisions#
Record the decision AND what you rejected. Six months later, the rejected options are the valuable part — they stop someone re-litigating a settled question, or repeating a mistake.
| # | Decision | Alternatives rejected | Why | Date |
|---|---|---|---|---|
| 1 |
Known constraints and debt#
| Item | Impact | Plan |
|---|---|---|