C4 Model Diagrams for Azure Systems
Visualizing Integration Architecture
Introduction
The C4 model (Context, Container, Component, Code) provides a hierarchical way to visualize software architecture at different levels of detail. For Azure integration systems, C4 diagrams help communicate architecture to different audiences—executives see the big picture, developers see the technical implementation.
This comprehensive guide covers:
- C4 levels — Understanding each level
- Integration examples — Diagrams for common patterns
- Tooling — Creating C4 diagrams
- Practices — Maintaining diagrams
C4 Model Overview
Four Levels
┌─────────────────────────────────────────────────────────────────────┐
│ C4 MODEL LEVELS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ LEVEL 1: CONTEXT │
│ ───────────────── │
│ Shows the system and its users/other systems │
│ Audience: Executives, non-technical stakeholders │
│ Example: "Order Processing System and its users" │
│ │
│ LEVEL 2: CONTAINER │
│ ────────────────── │
│ Shows the high-level building blocks │
│ Audience: Developers, architects │
│ Example: "API Management, Functions, Service Bus" │
│ │
│ LEVEL 3: COMPONENT │
│ ─────────────────── │
│ Shows what's inside each container │
│ Audience: Developers │
│ Example: "Order Function components" │
│ │
│ LEVEL 4: CODE │
│ ───────────── │
│ Shows implementation details (optional) │
│ Audience: Developers │
│ Example: "Class diagrams, API definitions" │
│ │
└─────────────────────────────────────────────────────────────────────┘
Integration System Diagrams
Level 1: System Context
┌─────────────────────────────────────────────────────────────────────┐
│ ORDER PROCESSING SYSTEM - SYSTEM CONTEXT │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Customer │ │ Order Processing │ │
│ │ Application │─────────▶│ System │ │
│ └──────────────┘ └─────────┬─-──────────┘ │
│ │ │
│ ┌──────────────┐ │ │
│ │ Warehouse │◀───────────────────┼──────┐ │
│ │ System │ │ │ │
│ └──────────────┘ ▼ │ │
│ ┌──────────┴───────────┐ │
│ │ Azure Services │ │
│ │ • API Management │ │
│ ┌──────────────┐ │ • Azure Functions │ │
│ │ Payment │◀────────────── │ • Service Bus │ │
│ │ Provider │ │ • Azure SQL │ │
│ └──────────────┘ └──────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Level 2: Container Diagram
┌┌────────────────────────────────────────────────────────────────────┐
│ ORDER PROCESSING - CONTAINER VIEW │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ API Management │ │
│ │ ┌─────────────────┐ ┌─────────────────────────────┐ │ │
│ │ │ Gateway │ │ REST API │ │ │
│ │ │ (TLS, Auth) │──│ /orders, /customers │ │ │
│ │ └─────────────────┘ └─────────────────────────────┘ │ │
│ └─────────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────┴───────────────────────────────┐ │
│ │ Azure Functions (Order Service) │ │
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │ Create Order │ │ Update Status │ │ Get Order │ │ │
│ │ │ Function │ │ Function │ │ Function │ │ │
│ │ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │ │
│ │ │ │ │ │ │
│ │ └──────────────────┼──────────────────┘ │ │
│ │ │ │ │
│ └─────────────────────────────┼───────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────┴───────────────────────────────┐ │
│ │ Service Bus │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │ │
│ │ │ orders-topic │ │ orders-queue │ │ DLQ │ │ │
│ │ │ (pub/subscribe) │ │ │ │(failed msgs)│ │ │
│ │ └────────┬────────┘ └────────┬────────┘ └─────────────┘ │ │
│ └───────────┼────────────────────┼────────────────────────────┘ │
│ │ │ │
│ ┌───────────┴────────────────────┴────────────────────────────┐ │
│ │ Data Stores │ │
│ │ ┌──────────────────┐ ┌─────────────────────────────┐ │ │
│ │ │ Azure SQL │ │ Azure Blob Storage │ │ │
│ │ │ (Orders DB) │ │ (Order Documents) │ │ │
│ │ └──────────────────┘ └─────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Level 3: Component Diagram
┌─────────────────────────────────────────────────────────────────────┐
│ ORDER FUNCTION - COMPONENT VIEW │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Create Order Function │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │
│ │ │ Order │ │ Validation │ │ Message │ │ │
│ │ │ Controller │──│ Service │──│ Publisher │ │ │
│ │ └─────────────┘ └──────┬──────┘ └─────────────────────┘ │ │
│ │ │ │ │
│ │ ┌─────────────┐ │ │ │
│ │ │ Repository │◀────────┘ │ │
│ │ │ │ │ │
│ │ └─────────────┘ │ |
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Interfaces │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │ │
│ │ │ IOrderRepository│ │ IMessagePublisher│ │ IValidator │ │ │
│ │ └─────────────────┘ └─────────────────┘ └──────────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────┼───────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Azure SQL │ │ Service Bus │ │ Validation Rules│ │
│ │ │ │ │ │ │ │
│ └──────────────────┘ └──────────────┘ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Tooling Options
Diagram Creation Tools
┌─────────────────────────────────────────────────────────────────────┐
│ DIAGRAM TOOLS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ PLANTUML │
│ • Text-based, code in version control │
│ • C4 extension available │
│ • Good for technical teams │
│ │
│ MEROA / STRUCTURIZR │
│ • Code-first approach │
│ • Generates multiple views │
│ • Integrates with IDE │
│ │
│ DIAGRAMS.NET / LUCICHART │
│ • Visual editor │
│ • Good for collaboration │
│ • Export to multiple formats │
│ │
│ VISUAL STUDIO CODE EXTENSIONS │
│ • PlantUML preview │
│ • Markdown diagram support │
│ │
└─────────────────────────────────────────────────────────────────────┘
PlantUML Example
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
LAYOUT_WITH_LEGEND()
Container(customer_app, "Customer App", "React", "Allows customers to place orders")
Container(api_gateway, "API Gateway", "Azure API Management", "API entry point")
Container(order_function, "Order Function", "Azure Functions", "Handles order processing")
Container(payment_service, "Payment Service", "Azure Functions", "Processes payments")
ContainerDb(order_db, "Order Database", "Azure SQL", "Stores orders")
ContainerDb(orders_topic, "Orders Topic", "Azure Service Bus", "Message broker")
Rel(customer_app, api_gateway, "Places order", "HTTPS")
Rel(api_gateway, order_function, "Forwards request", "HTTPS")
Rel(order_function, payment_service, "Processes payment", "HTTPS")
Rel(order_function, order_db, "Stores order", "SQL")
Rel(order_function, orders_topic, "Publishes event", "AMQP")
SHOW_LEGEND()
@enduml
Best Practices
Diagram Maintenance
┌─────────────────────────────────────────────────────────────────────┐
│ C4 BEST PRACTICES │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ WHEN TO CREATE: │
│ ✓ New system or major feature │
│ ✓ Architecture changes │
│ ✓ Onboarding new team members │
│ ✓ Technical documentation │
│ │
│ MAINTENANCE: │
│ ✓ Keep diagrams in version control │
│ ✓ Update when architecture changes │
│ ✓ Review quarterly for accuracy │
│ ✓ Link diagrams to ADRs │
│ │
│ TIPS: │
│ • Use consistent notation │
│ • Don't show everything - focus on relevant │
│ • Include technology choices │
│ • Label relationships with protocols │
│ │
└─────────────────────────────────────────────────────────────────────┘
Related Topics
- ADR Process — Architecture decision records
- Capacity Planning — Resource planning
Azure Integration Hub - Architect Level Solution Design & Architecture Reviews