Building a C4 Diagram
Step-by-step guide to creating C4 model architecture diagrams
This guide walks you through creating a complete C4 model diagram set in Archflow, from a high-level context view down to component details.
What is the C4 Model?
The C4 model is a set of four diagram types for visualizing software architecture at different levels of abstraction:
- Context --- How your system fits in the world
- Container --- The high-level technical building blocks
- Component --- The internals of each container
- Code --- (Optional) Class-level detail
Archflow supports the first three levels natively through its system hierarchy.
Example: E-Commerce Platform
Let's model an e-commerce platform step by step.
Level 1: System Context
Start by identifying the main actors and external systems.
Create these systems on the Systems page (click Add Element for each):
| System | Type | Description |
|---|---|---|
| Customer | Person | Browses products and places orders |
| E-Commerce Platform | Software System | Our main application |
| Payment Provider | Software System | Processes credit card payments (external) |
| Email Service | Software System | Sends transactional emails (external) |
| Shipping API | Software System | Manages delivery logistics (external) |
Create these connections from the Connections page or directly on the canvas by dragging between system handles:
| From | To | Description | Technology |
|---|---|---|---|
| Customer | E-Commerce Platform | Browses and purchases | HTTPS |
| E-Commerce Platform | Payment Provider | Processes payments | REST/HTTPS |
| E-Commerce Platform | Email Service | Sends order confirmations | SMTP |
| E-Commerce Platform | Shipping API | Creates shipments | REST/HTTPS |
Create a diagram view: Navigate to Views, click Create Diagram, and name it "System Context". Open the Editor tab, then click Add to View to place all these systems on the canvas. Arrange the Customer at the top, your platform in the center, and external systems around it.
Level 2: Container Diagram
Now zoom into the E-Commerce Platform. On the Systems page, click Add Element and create these systems with "E-Commerce Platform" as the parent:
| Container | Type | Technology | Description |
|---|---|---|---|
| Web Application | Container | React, Next.js | Customer-facing storefront |
| API Server | Container | Node.js, Express | Backend business logic |
| Database | Container | PostgreSQL | Stores products, orders, users |
| Search Index | Container | Elasticsearch | Product search and filtering |
| Message Queue | Container | RabbitMQ | Async processing |
Add connections between containers (from the canvas or Connections page):
| From | To | Description | Technology |
|---|---|---|---|
| Web Application | API Server | API calls | REST/HTTPS |
| API Server | Database | Reads/writes data | Prisma/SQL |
| API Server | Search Index | Indexes products | REST |
| API Server | Message Queue | Publishes events | AMQP |
| Web Application | Search Index | Search queries | REST |
Create a diagram view called "Container View" and add these internal containers using the Editor canvas.
Level 3: Component Diagram
Pick one container to decompose further. Let's detail the API Server by creating these as children of "API Server" on the Systems page:
| Component | Type | Description |
|---|---|---|
| Auth Controller | Component | Handles authentication and authorization |
| Product Controller | Component | Product CRUD operations |
| Order Controller | Component | Order management |
| Payment Service | Component | Payment processing integration |
| Notification Service | Component | Email and push notifications |
Create a "API Components" diagram view to visualize these components and their interactions.
Layout Tips
- Context diagrams: Place your system in the center, users on top, external systems around the edges
- Container diagrams: Arrange by data flow, typically left-to-right or top-to-bottom
- Component diagrams: Group related components together
- Use descriptions: Every system and connection should have a description --- this improves AI documentation quality
- Be consistent: Use the same terminology across all diagram levels
- Use Archie: Ask the AI assistant for suggestions on system organization
Next Steps
Once your C4 diagrams are complete: