Master this essential documentation concept
A framework for visualizing software architecture using four levels of diagrams: Context, Containers, Components, and Code, designed to communicate system design clearly.
A framework for visualizing software architecture using four levels of diagrams: Context, Containers, Components, and Code, designed to communicate system design clearly.
Architecture review sessions are where your team's C4 Model decisions come to life. Engineers walk through Context diagrams to align stakeholders, debate Container boundaries in design meetings, and explain Component relationships during onboarding calls. These conversations are rich with the reasoning behind your system's structure — why a particular service boundary exists, or why the Code level was scoped the way it was.
The problem is that recording these sessions doesn't make them usable. When a new developer needs to understand how your C4 Model maps to the actual codebase, searching through a two-hour architecture walkthrough is rarely practical. Critical decisions about Container responsibilities or Context-level dependencies stay buried in timestamps no one remembers.
Converting those recordings into structured documentation changes how your team references architectural knowledge. A searchable transcript with extracted decisions means someone can find the exact moment your team agreed on a Container boundary — without scrubbing through video. You can also surface recurring C4 Model terminology across multiple sessions, making it easier to spot where definitions drift over time or where diagrams no longer match what was actually built.
If your team regularly records architecture discussions, design reviews, or onboarding walkthroughs that involve system diagrams, turning those recordings into indexed documentation is worth exploring.
New engineers joining a team with 20+ microservices spend 2-3 weeks reverse-engineering architecture from code and Confluence pages that are months out of date, delaying their first meaningful contribution.
A C4 Level 1 Context diagram immediately shows how the platform fits into the business ecosystem, while Level 2 Container diagrams reveal which microservices exist, what technology they use, and how they communicate — all without reading a single line of code.
['Create a Level 1 Context diagram showing the platform, its users (internal staff, customers, partners), and external systems (Stripe, Salesforce, Auth0) using C4-PlantUML or Structurizr.', 'Build Level 2 Container diagrams for each bounded domain (e.g., Payments Domain, User Domain), listing each microservice with its tech stack and inter-service communication protocols.', "Add a 'Key Decisions' annotation layer to each diagram noting why certain architectural choices were made (e.g., why Kafka was chosen over REST for order events).", 'Embed these diagrams in the engineering onboarding Notion or Confluence page with a guided reading order: Context → Containers → Components for the service the new hire will own.']
New engineers report understanding the system architecture within their first day, reducing the onboarding ramp-up from 2-3 weeks to under 5 days and cutting the number of architecture questions asked in Slack by approximately 60%.
Engineering teams planning a migration from on-premise infrastructure to AWS struggle to explain the before/after architecture to product managers, finance teams, and executives who cannot interpret AWS architecture diagrams filled with service icons and VPC notation.
C4 Level 1 and Level 2 diagrams use plain English labels and intentionally abstract away infrastructure details, making it possible to show stakeholders exactly what changes in terms of system responsibilities and data flows without requiring cloud expertise.
["Draw a 'Current State' C4 Level 2 diagram showing the existing on-premise containers (Web Server, App Server, Oracle DB, File Storage) and their relationships.", "Draw a 'Future State' C4 Level 2 diagram replacing on-premise containers with AWS equivalents (EC2 Auto Scaling Group, RDS Aurora, S3) using the same C4 notation so the structural comparison is immediately clear.", 'Present both diagrams side-by-side in a stakeholder deck, annotating which containers change, which stay the same, and which new external systems are introduced (e.g., AWS CloudFront as a new CDN).', 'Use the Level 1 Context diagram to confirm that the migration does not change any user-facing behavior or external integrations, reassuring stakeholders about scope.']
Stakeholders approve the migration plan in a single review meeting rather than requiring multiple clarification sessions, and the finance team can accurately scope cost changes because they understand which components are being replaced.
A monolithic Rails application is being split into bounded contexts following DDD principles, but developers disagree on where service boundaries should be drawn and which components belong to which domain, causing repeated architecture debates in pull request reviews.
C4 Level 2 and Level 3 diagrams make proposed service boundaries explicit and visual, turning abstract DDD boundary discussions into concrete diagrams that can be reviewed, versioned in Git, and iterated on asynchronously before any code is written.
['Model the current monolith as a single Container in a Level 2 diagram, then create a proposed future-state Level 2 diagram showing the target bounded contexts (e.g., Order Management Service, Inventory Service, Notification Service) as separate containers.', 'For each proposed service, create a Level 3 Component diagram listing the specific Rails controllers, service objects, and background jobs that would move into that container.', 'Store all Structurizr DSL or C4-PlantUML files in a /docs/architecture directory in the monorepo and require architecture diagram updates as part of the Definition of Done for refactoring tickets.', 'Run a structured architecture review session where engineers walk through the Level 2 diagram to surface disagreements about which components belong to which bounded context, resolving debates with reference to the diagrams rather than verbal descriptions.']
The team reaches consensus on service boundaries in two structured sessions instead of debating across 15+ pull requests, and the finalized C4 diagrams serve as the authoritative contract for the 6-month refactoring effort.
Security auditors and compliance officers require documentation showing where sensitive customer data flows, which systems store PII, and what trust boundaries exist — but engineering teams have no standardized way to produce this documentation, leading to last-minute scrambles before audits.
C4 Level 1 and Level 2 diagrams with security annotations (trust boundaries, data classification tags, encryption indicators) provide auditors with a structured view of data flows and system boundaries that directly maps to SOC 2 control requirements.
['Create a C4 Level 1 Context diagram annotating which external systems receive or send PII (e.g., Stripe receives payment data, SendGrid receives email addresses) and marking trust boundaries between internal and external systems.', "Build a C4 Level 2 Container diagram tagging each container with its data classification level (e.g., 'Stores PII: Yes/No'), encryption-at-rest status, and network zone (public subnet, private subnet, isolated DB subnet).", 'Add a C4 Level 3 Component diagram for the Authentication Service showing the specific components handling credential storage, session management, and MFA — the components most scrutinized in security audits.', 'Generate these diagrams from Structurizr DSL so they can be regenerated automatically when the architecture changes, ensuring the compliance documentation stays current between annual audits.']
The engineering team provides auditors with a complete, up-to-date architecture documentation package in under 2 hours, reducing audit preparation time from 3 weeks to 2 days and receiving zero findings related to missing architecture documentation.
The C4 Model's power lies in its layered abstraction — Level 1 Context diagrams are designed for business stakeholders and executives, while Level 3 Component diagrams are for developers working on a specific service. Mixing levels in a single conversation or document forces audiences to context-switch between abstraction layers, causing confusion. Always lead with the highest-level diagram appropriate for your audience before drilling down.
Diagrams stored as images in Confluence or Google Slides become stale within weeks because they are disconnected from the development workflow. Storing Structurizr DSL or C4-PlantUML source files in the same Git repository as the application code means architecture diagrams are updated in the same pull request as the code change, and diagram history is tracked in version control. This 'diagrams as code' approach also enables diff reviews on architecture changes.
One of the most valuable pieces of information a C4 diagram communicates is the technology stack of each container and component. Omitting technology labels forces readers to look up this information elsewhere, breaking the self-contained nature of the diagram. In C4-PlantUML and Structurizr, every Container() and Component() element accepts a technology parameter — always populate it with the specific runtime, framework, or database engine (e.g., 'Node.js 20 / Express', 'PostgreSQL 15', 'Apache Kafka 3.5').
Unlabeled arrows between containers are one of the most common mistakes in C4 diagrams. An arrow from 'Web App' to 'API Server' with no label tells the reader nothing about whether the communication is synchronous REST, async messaging via Kafka, gRPC, or a WebSocket connection. Every relationship in a C4 diagram should specify the communication mechanism, data format, and direction. This is critical for security reviews, incident debugging, and integration planning.
Teams often make the mistake of creating separate, disconnected C4 diagrams for different purposes — one for onboarding, one for the security audit, one for the architecture review — which quickly diverge from each other. Structurizr DSL allows you to define your architecture once as a single model and generate multiple views (System Context, Container, Component, Deployment) from that single source of truth. This ensures all diagrams remain consistent and only require updates in one place.
Join thousands of teams creating outstanding documentation
Start Free Trial