C4 Model for Software Architecture

Best Practice: C4 Model for Software Architecture

The C4 model, created by Simon Brown, is a simple, hierarchical approach to diagramming software architecture. It describes a system at four nested levels of abstraction: System Context (how the system fits in its environment), Containers (the deployable or runnable units), Components (the major building blocks inside a container), and Code (class-level detail, used sparingly). Think of it as a map you can zoom in and out of. The value is a shared, unambiguous notation that both new developers and executives can read. For modernization, C4 diagrams make the current and target architectures explicit so migration scope and risk are visible.

Step-by-Step Implementation Guidance

1. Start at the top: draw a System Context diagram showing your system, its users, and external systems.
2. Zoom in to the Container level: show applications, services, data stores, and how they communicate.
3. For complex containers, draw Component diagrams of the major internal building blocks.
4. Use the Code level rarely, only when class detail genuinely helps.
5. Apply a consistent legend so every element and relationship is labeled clearly.
6. Keep diagrams as code (for example, Structurizr or PlantUML) so they live with the repo.
7. Update diagrams as the architecture evolves, especially during migration.

Common Mistakes Teams Make When Ignoring This Practice

• Boxes-and-lines diagrams with no agreed meaning for shapes or arrows.
• Mixing abstraction levels in one diagram so it confuses readers.
• Diagrams that exist only in a slide deck and rot immediately.
• Drawing the Code level when a Container view would suffice.
• No labels, so relationships are ambiguous.

Tools and Techniques That Support This Practice

• Structurizr for diagrams-as-code aligned to C4.
• PlantUML with the C4-PlantUML library and Mermaid C4 diagrams.
• IcePanel and diagrams.net (draw.io) C4 templates.
• Version control so diagrams change alongside code.

How This Practice Applies to Different Migration Types

• Cloud Migration: Use Container diagrams to compare on-premises and target cloud topologies and spot dependencies.
• Database Migration: Show data stores and their consumers at the Container level to plan safe data moves.
• SaaS Migration: Map external system relationships in the Context diagram to expose integration work.
• Codebase Migration: Use Component diagrams to define strangler-fig seams between old and new code.

Checklist

• A System Context diagram exists for the system.
• Container-level diagrams show deployable units and communication.
• Component diagrams exist only where they add value.
• Every diagram has a clear, consistent legend.
• Diagrams are stored as code in version control.
• Abstraction levels are not mixed within a diagram.
• Diagrams are updated as architecture changes.