Using C4 for the high-level “narrative” and UML for the technical “fine print”
One of the most powerful — yet frequently underutilized — aspects of professional architecture modeling is the complementary relationship between the C4 Model and UML. Rather than treating them as competitors or forcing one notation to do everything, mature teams use C4 for the narrative (the story, the context, the big-picture understanding) and UML for the fine print (precise, detailed technical specifications where needed). This hybrid approach delivers the best of both worlds: lightweight communication + rigorous engineering detail.
Why They Complement Each Other So Well
| Aspect | C4 Model (Narrative Layer) | UML (Fine-Print Layer) |
|---|---|---|
| Primary purpose | Communicate architecture to humans (technical & non-technical) | Precisely specify implementation details & contracts |
| Level of abstraction | High to medium (Context → Containers → Components) | Low to medium (classes, sequences, states, activities) |
| Notation complexity | Extremely lightweight — boxes, lines, simple labels | Rich & formal — 14 diagram types, stereotypes, constraints |
| Audience | Everyone: executives, product, developers, ops, auditors | Primarily developers & architects needing implementation clarity |
| Maintenance cost | Low — especially when text-based (PlantUML/C4-PlantUML) | Higher — detailed & sensitive to code changes |
| Best for | Storytelling, onboarding, decision rationale, boundary definition | Class structures, method signatures, state transitions, algorithms |
| Tooling | PlantUML, Structurizr, IcePanel, Visual Paradigm | Enterprise Architect, Visual Paradigm, StarUML, PlantUML (subset) |
The synergy rule is simple:
Use C4 to answer “what is this system, why does it exist, and how does it fit together at a high level?” Use UML (selectively) to answer “exactly how is this part implemented in code?”
Practical Patterns for C4 + UML Synergy
- Narrative with C4, Drill-Down with UML
- Level 1–2: Pure C4 (System Context + Container diagrams)
- Level 3: Mostly C4 Component diagram (logical responsibilities & interfaces)
- When a component needs deep explanation: attach or link a UML Class diagram showing key classes, interfaces, value objects, and relationships
- Example: “Order Placement” component → UML class diagram of Order, OrderLine, Money, CustomerId, OrderStatus enum, invariants, and factory methods.
- Dynamic Behavior
- Use C4 Dynamic Diagram (simplified sequence) for high-level runtime flows (e.g., “Customer places order → payment → fulfillment”)
- When a critical interaction needs precision (e.g., payment authorization handshake): supplement with UML Sequence Diagram showing lifelines, messages, returns, alt fragments, and exceptions.
- State & Lifecycle
- C4 rarely shows state transitions
- UML State Machine Diagram for complex domain objects (e.g., Order lifecycle: Pending → Paid → Shipped → Delivered → Returned → Refunded) with guards, triggers, and entry/exit actions.
- Data Structure Detail
- C4 treats databases as containers (Level 2) or components (Level 3)
- UML Class Diagram or ERD (UML-style) for schema: tables, columns, relationships, constraints, indexes
- Often generated from code (JPA entities, SQL scripts) or maintained in Visual Paradigm.
- Interface Contracts
- C4 shows “calls PaymentProviderPort” as a relationship
- UML Component or Class Diagram shows the exact PaymentProviderPort interface with method signatures, parameters, return types, and exceptions.
Guidelines for Effective Hybrid Use
- Keep UML minimal & focused — only for the 5–10% of the system that is truly complex or critical (never apply UML everywhere).
- Embed or hyperlink — In Visual Paradigm or living documentation portals, nest UML diagrams inside C4 components or link them (“Click here for detailed class model”).
- Generate where possible — Use IDE plugins (IntelliJ PlantUML integration), reverse-engineering tools, or AI-assisted generation to keep UML current.
- Version together — Store both C4-PlantUML text and UML source (PlantUML or .vpp) in the same repo folder.
- Audience routing — C4 views go to everyone; UML views are developer-only unless required for compliance/audit.
- Avoid notation wars — Never argue “C4 vs UML”; they serve different purposes. Simon Brown himself encourages selective UML use when C4’s simplicity isn’t sufficient.
Real-World Example
In a large e-commerce platform:
- C4 Level 1 — System Context: shows Customer, Mobile App, E-Commerce Platform, Stripe, Email Service
- C4 Level 2 — Container Diagram: Mobile App → API Gateway → Order Service → PostgreSQL + Kafka
- C4 Level 3 — Component Diagram inside Order Service: Order Placement Workflow → Payment Orchestrator → Inventory Adapter
- UML fine print (attached to Payment Orchestrator component):
- Class diagram of PaymentRequest, PaymentResponse, PaymentStatus, PaymentProvider interface hierarchy (StripeProvider, PayPalProvider)
- Sequence diagram for the 3-way handshake with Stripe (including error paths and retries)
This combination gives executives the story they need while giving developers the precise blueprint they need — without forcing UML complexity onto everyone.
Bottom Line
C4 provides the compelling, zoomable narrative that makes architecture accessible and maintainable. UML provides the surgical precision required for implementation-critical areas.
Mastering their synergy means you can communicate at any level of detail, to any audience, while keeping the overall modeling effort lightweight and sustainable.
In the hands-on section ahead, you’ll practice this hybrid approach: starting with a pure C4 model, identifying where UML adds value, generating/selecting the right UML views, and integrating them into a professional Visual Paradigm workspace for final delivery.