Most engineers learn to draw boxes and arrows. Few learn that different boxes and arrows mean completely different things. An architecture review collapses when everyone in the room is looking at a different layer of the system. One person is thinking about services. Another is thinking about data flows. A third is thinking about deployment topology. They are all looking at the same diagram and seeing three different systems.
There are five diagram types, each designed to answer a specific question. Using the right one prevents the wrong conversation.
Why Diagram Types Exist
A diagram is a compression. It takes a system with thousands of moving parts and collapses it to a single page. Every compression discards information. The question is: which information are you discarding, and for whom?
A diagram that shows everything shows nothing useful. The five types exist because there are five distinct audiences with five distinct questions. Mixing them produces a diagram that answers none of them clearly.
1. Context Diagram
Question answered: What does this system do, and who uses it?
A context diagram shows one box: your system. Around it, every external actor that touches the system — users, third-party APIs, upstream data sources, downstream consumers. Lines connect them. No internals. No components. No data structures.
┌──────────────┐
Mobile User ───▶│ │───▶ Payment Gateway
│ Order │
Web Browser ───▶│ Service │───▶ Inventory System
│ │
Merchant API ──▶│ │───▶ Email Provider
└──────────────┘
This is the diagram you show to a new team member on day one, to a product manager, or to an executive. It is deliberately shallow because depth would hide the boundary — which is the only thing this diagram is designed to show.
When a diagram needs to communicate what a system is responsible for and what it is not responsible for, this is the one to reach for.
2. Container Diagram
Question answered: What are the major deployable units, and how do they communicate?
A container diagram shows the major runtime units: services, databases, queues, caches, frontend applications. Each box is something you could deploy, scale, or restart independently. Lines show communication: HTTP, gRPC, message queues, database connections.
┌─────────────┐ HTTP ┌─────────────┐ SQL ┌──────────────┐
│ React SPA │────────────▶│ API Server │──────────▶│ PostgreSQL │
│ (browser) │ │ (Node.js) │ │ (primary) │
└─────────────┘ └──────┬──────┘ └──────────────┘
│
Redis │ GET/SET
▼
┌─────────────┐ Publish ┌─────────────┐
│ Redis Cache│────────────▶│ RabbitMQ │
└─────────────┘ └──────┬──────┘
│
┌──────▼──────┐
│ Worker │
│ Service │
└─────────────┘
This is the diagram software engineers most commonly call "the architecture diagram." It answers the question that matters most when debugging, scaling, or planning a migration: where does my code actually run, and what talks to what?
A container diagram does not show individual classes, functions, or data schemas. It stays at the deployment unit level.
3. Component Diagram
Question answered: How is the logic inside one container organised?
A component diagram zooms into a single container and shows the internal structure: modules, services, layers, repositories. It answers the question a new engineer asks when they join a team and want to understand how a specific service is structured.
API Server (Node.js)
┌─────────────────────────────────────────────────────┐
│ │
│ ┌───────────────┐ ┌───────────────────────┐ │
│ │ Route Layer │─────▶│ Auth Middleware │ │
│ │ (Express) │ └───────────────────────┘ │
│ └───────┬───────┘ │
│ │ │
│ ┌───────▼───────┐ ┌───────────────────────┐ │
│ │ Service Layer│─────▶│ Cache Service │ │
│ │ (business │ │ (Redis client) │ │
│ │ logic) │ └───────────────────────┘ │
│ └───────┬───────┘ │
│ │ │
│ ┌───────▼───────┐ ┌───────────────────────┐ │
│ │ Repository │─────▶│ DB Connection Pool │ │
│ │ Layer │ │ (pg) │ │
│ └───────────────┘ └───────────────────────┘ │
└─────────────────────────────────────────────────────┘
Component diagrams are the most frequently misused type. Engineers draw them as monolithic blobs of dependencies rather than as clear layers. The discipline here is the same as in the code itself: high-level components should not depend on low-level details.
4. Data Flow Diagram
Question answered: Where does data come from, how is it transformed, and where does it go?
A data flow diagram follows data, not components. It shows sources, transformations, stores, and sinks. The boxes are not services — they are processes that act on data. The arrows carry data, not function calls.
User Upload Raw Events Cleaned Events
─────────▶ Ingest ─────────▶ Validate ──────────▶ Enrich
(S3) ──────────▶ & Clean (add geo,
Dead letter (drop user metadata)
queue malformed) │
│
┌───────────────────────────────────┘
▼
Aggregation Reports Store
Analyst ◀── (hourly ◀── Feature Store ◀── (BigQuery)
Dashboard rollups)
This diagram is essential for two situations: designing a data pipeline and auditing where sensitive data travels. A security review of a system that handles user PII should always start with a data flow diagram. If the diagram cannot be drawn clearly, the data boundaries are not clear either.
5. Deployment Diagram
Question answered: Where does this run, and how does it connect to infrastructure?
A deployment diagram shows physical or cloud infrastructure: servers, Kubernetes clusters, availability zones, load balancers, CDN edges. It maps containers from the container diagram onto the infrastructure that runs them.
┌─────── AWS Region: us-east-1 ──────────────┐
│ │
Users ──▶ CloudFront ──▶│ ┌─── AZ: us-east-1a ──┐ ┌── AZ: 1b ──┐ │
│ │ ┌──────────────┐ │ │ ┌────────┐ │ │
│ │ │ App Server │ │ │ │ App │ │ │
│ │ │ (EC2 t3.m) │ │ │ │ Server │ │ │
│ │ └──────┬───────┘ │ │ └───┬────┘ │ │
│ └─────────┼────────────┘ └─────┼──────┘ │
│ │ │ │
│ ┌─────────▼──── RDS ────────────▼──────┐ │
│ │ PostgreSQL primary │ Read replica │ │
│ └────────────────────────────────────── ┘ │
└─────────────────────────────────────────────┘
This is the diagram an SRE reaches for at 3 AM during an outage. It answers: if this availability zone goes down, what breaks? It makes the blast radius of any failure visible before the failure happens.
How to Choose
| Question you need to answer | Diagram to use |
|---|---|
| What is this system responsible for? | Context |
| What are the main services, and how do they talk? | Container |
| How is the logic inside one service structured? | Component |
| Where does data come from and go? | Data Flow |
| What happens if this availability zone fails? | Deployment |
The Most Common Mistake
The most common mistake is drawing a container diagram with component-level detail and deployment-level infrastructure in the same image. The result answers no question cleanly. Every element competes with every other element for attention.
Before drawing, answer one question: what decision does this diagram need to support? That answer picks the type. The type determines what belongs on the page and what gets left off.
How This Connects to the Series
The five types map directly to the Architecture Diagrams framework (F7) in the Reference Book, where each corresponds to a level of abstraction in the system hierarchy.