tools-only C4 Model Diagrams
The C4 model provides a hierarchical way to visualize software architecture at different levels of abstraction: Context, Containers, Components, and Code.
C4 Model Levels
- System Context - Shows the system and its users/external systems
- Container - Shows applications, databases, and services within the system
- Component - Shows internal structure of containers
- Code - Class diagrams showing implementation details (use regular class diagrams)
C4 Context Diagram
Shows the big picture: your system and its relationships with users and external systems.
Basic Syntax
C4Context
title System Context for Banking System
Person(customer, "Customer", "A banking customer")
System(banking, "Banking System", "Allows customers to manage accounts")
System_Ext(email, "Email System", "Sends emails")
Rel(customer, banking, "Uses")
Rel(banking, email, "Sends emails via")
Elements
People:
C4Context
Person(user, "User", "Description")
Person_Ext(external, "External User", "Outside organization")
Systems:
C4Context
System(internal, "Internal System", "Description")
System_Ext(external, "External System", "Description")
SystemDb(database, "Database System", "Description")
SystemDb_Ext(external_db, "External DB", "Description")
SystemQueue(queue, "Message Queue", "Description")
SystemQueue_Ext(external_queue, "External Queue", "Description")
Relationships:
C4Context
Rel(from, to, "Label")
Rel(from, to, "Label", "Optional Technology")
BiRel(system1, system2, "Bidirectional")
Comprehensive Context Example
C4Context
title System Context - E-Commerce Platform
Person(customer, "Customer", "Shops online")
Person(admin, "Administrator", "Manages products and orders")
Person_Ext(delivery, "Delivery Personnel", "Delivers orders")
System(ecommerce, "E-Commerce Platform", "Online shopping platform")
System_Ext(payment, "Payment Gateway", "Processes payments")
System_Ext(email, "Email Service", "Sends notifications")
System_Ext(sms, "SMS Service", "Sends SMS alerts")
System_Ext(analytics, "Analytics Platform", "Tracks user behavior")
SystemQueue_Ext(shipping, "Shipping API", "Calculates shipping rates")
Rel(customer, ecommerce, "Browses products, places orders")
Rel(admin, ecommerce, "Manages catalog, reviews orders")
Rel(delivery, ecommerce, "Updates delivery status")
Rel(ecommerce, payment, "Processes payments via", "HTTPS/REST")
Rel(ecommerce, email, "Sends emails via", "SMTP")
Rel(ecommerce, sms, "Sends SMS via", "REST API")
Rel(ecommerce, analytics, "Tracks events", "JavaScript SDK")
Rel(ecommerce, shipping, "Gets shipping rates", "REST API")
UpdateRelStyle(customer, ecommerce, $offsetX="-50", $offsetY="-30")
UpdateRelStyle(admin, ecommerce, $offsetX="50", $offsetY="-30")
C4 Container Diagram
Zooms into the system to show containers (applications, databases, services).
Basic Syntax
C4Container
title Container Diagram for Banking System
Person(customer, "Customer")
Container_Boundary(banking, "Banking System") {
Container(web, "Web Application", "React", "Delivers static content")
Container(api, "API Application", "Node.js", "Provides banking API")
ContainerDb(db, "Database", "PostgreSQL", "Stores account data")
}
Rel(customer, web, "Uses", "HTTPS")
Rel(web, api, "Makes API calls", "HTTPS/JSON")
Rel(api, db, "Reads/writes", "SQL/TCP")
Container Elements
C4Container
Container(app, "Application", "Technology", "Description")
ContainerDb(db, "Database", "PostgreSQL", "Description")
ContainerQueue(queue, "Queue", "RabbitMQ", "Description")
Container_Ext(external, "External Service", "Tech", "Description")
Container Boundaries
C4Container
Container_Boundary(boundary_name, "Boundary Label") {
Container(app1, "App 1", "Tech")
Container(app2, "App 2", "Tech")
}
Comprehensive Container Example
C4Container
title Container Diagram - E-Commerce Platform
Person(customer, "Customer")
Person(admin, "Admin")
System_Ext(payment, "Payment Gateway")
System_Ext(email, "Email Service")
Container_Boundary(frontend, "Frontend") {
Container(web, "Web App", "React", "Delivers UI")
Container(mobile, "Mobile App", "React Native", "Mobile UI")
}
Container_Boundary(backend, "Backend Services") {
Container(api, "API Gateway", "Node.js/Express", "Routes requests")
Container(auth, "Auth Service", "Node.js", "Handles authentication")
Container(catalog, "Catalog Service", "Python/FastAPI", "Manages products")
Container(order, "Order Service", "Java/Spring", "Processes orders")
Container(notification, "Notification Service", "Node.js", "Sends notifications")
}
Container_Boundary(data, "Data Layer") {
ContainerDb(postgres, "Main Database", "PostgreSQL", "Stores core data")
ContainerDb(mongo, "Product DB", "MongoDB", "Product catalog")
ContainerDb(redis, "Cache", "Redis", "Session & caching")
ContainerQueue(queue, "Message Queue", "RabbitMQ", "Async processing")
}
Rel(customer, web, "Uses", "HTTPS")
Rel(customer, mobile, "Uses", "HTTPS")
Rel(admin, web, "Manages via", "HTTPS")
Rel(web, api, "Makes calls", "HTTPS/JSON")
Rel(mobile, api, "Makes calls", "HTTPS/JSON")
Rel(api, auth, "Authenticates", "gRPC")
Rel(api, catalog, "Gets products", "REST")
Rel(api, order, "Creates orders", "REST")
Rel(auth, postgres, "Reads/writes users", "SQL")
Rel(catalog, mongo, "Reads/writes products", "MongoDB Protocol")
Rel(order, postgres, "Reads/writes orders", "SQL")
Rel(auth, redis, "Stores sessions", "Redis Protocol")
Rel(api, redis, "Caches data", "Redis Protocol")
Rel(order, queue, "Publishes events", "AMQP")
Rel(notification, queue, "Consumes events", "AMQP")
Rel(notification, email, "Sends via", "SMTP")
Rel(order, payment, "Processes payment", "HTTPS/REST")
C4 Component Diagram
Zooms into a container to show its internal components.
Basic Syntax
C4Component
title Component Diagram for API Application
Container(web, "Web App", "React")
ContainerDb(db, "Database", "PostgreSQL")
System_Ext(email, "Email System")
Container_Boundary(api, "API Application") {
Component(controller, "Controller", "Express Router", "Handles HTTP")
Component(service, "Business Logic", "Service Layer", "Core logic")
Component(repository, "Data Access", "Repository", "DB operations")
Component(emailClient, "Email Client", "Client", "Sends emails")
}
Rel(web, controller, "Makes requests", "HTTPS")
Rel(controller, service, "Uses")
Rel(service, repository, "Uses")
Rel(repository, db, "Reads/writes", "SQL")
Rel(service, emailClient, "Sends emails via")
Rel(emailClient, email, "Sends", "SMTP")
Comprehensive Component Example
C4Component
title Component Diagram - Order Service
Container(api_gateway, "API Gateway", "Node.js")
ContainerDb(postgres, "Database", "PostgreSQL")
ContainerQueue(queue, "Message Queue", "RabbitMQ")
System_Ext(payment, "Payment Gateway")
System_Ext(inventory, "Inventory Service")
Container_Boundary(order_service, "Order Service") {
Component(controller, "REST Controllers", "Spring MVC", "HTTP endpoints")
Component(order_logic, "Order Manager", "Service", "Order processing logic")
Component(payment_client, "Payment Client", "REST Client", "Payment integration")
Component(inventory_client, "Inventory Client", "REST Client", "Inventory integration")
Component(repository, "Order Repository", "JPA", "Database operations")
Component(event_publisher, "Event Publisher", "Component", "Publishes domain events")
Component(validator, "Order Validator", "Component", "Validates orders")
}
Rel(api_gateway, controller, "Routes requests", "HTTPS/REST")
Rel(controller, order_logic, "Delegates to")
Rel(controller, validator, "Validates with")
Rel(order_logic, payment_client, "Processes payment")
Rel(order_logic, inventory_client, "Checks stock")
Rel(order_logic, repository, "Persists orders")
Rel(order_logic, event_publisher, "Publishes events")
Rel(payment_client, payment, "Calls", "HTTPS/REST")
Rel(inventory_client, inventory, "Calls", "HTTPS/REST")
Rel(repository, postgres, "Reads/writes", "JDBC/SQL")
Rel(event_publisher, queue, "Publishes to", "AMQP")
Microservices Architecture Example
C4Container
title Microservices Architecture - Streaming Platform
Person(user, "User", "Platform user")
Person(creator, "Content Creator", "Uploads videos")
System_Ext(cdn, "CDN", "Delivers media")
System_Ext(storage, "Object Storage", "Stores videos")
System_Ext(transcoding, "Transcoding Service", "Processes videos")
Container_Boundary(frontend, "Frontend Layer") {
Container(web, "Web Application", "Next.js", "Server-rendered UI")
Container(mobile, "Mobile Apps", "React Native", "iOS/Android apps")
}
Container_Boundary(api_layer, "API Layer") {
Container(api_gateway, "API Gateway", "Kong", "Routing, auth, rate limiting")
Container(graphql, "GraphQL Gateway", "Apollo", "Unified API")
}
Container_Boundary(services, "Microservices") {
Container(auth, "Auth Service", "Go", "Authentication & authorization")
Container(user, "User Service", "Node.js", "User profiles & preferences")
Container(video, "Video Service", "Python", "Video metadata & management")
Container(recommendation, "Recommendation Engine", "Python/ML", "Content recommendations")
Container(analytics, "Analytics Service", "Go", "View tracking & metrics")
Container(search, "Search Service", "Elasticsearch", "Content search")
Container(comment, "Comment Service", "Node.js", "Comments & discussions")
}
Container_Boundary(data, "Data Layer") {
ContainerDb(user_db, "User Database", "PostgreSQL", "User data")
ContainerDb(video_db, "Video Database", "MongoDB", "Video metadata")
ContainerDb(analytics_db, "Analytics DB", "ClickHouse", "Analytics data")
ContainerDb(cache, "Cache Layer", "Redis Cluster", "Caching & sessions")
ContainerQueue(event_bus, "Event Bus", "Kafka", "Event streaming")
ContainerDb(search_index, "Search Index", "Elasticsearch", "Search data")
}
Rel(user, web, "Uses", "HTTPS")
Rel(creator, web, "Uploads via", "HTTPS")
Rel(user, mobile, "Uses", "HTTPS")
Rel(web, api_gateway, "API calls", "HTTPS/REST")
Rel(mobile, api_gateway, "API calls", "HTTPS/REST")
Rel(web, graphql, "Queries", "HTTPS/GraphQL")
Rel(api_gateway, auth, "Authenticates", "gRPC")
Rel(graphql, video, "Gets videos", "gRPC")
Rel(graphql, user, "Gets users", "gRPC")
Rel(graphql, recommendation, "Gets recommendations", "gRPC")
Rel(video, storage, "Stores videos", "S3 API")
Rel(video, transcoding, "Sends for transcoding", "REST")
Rel(video, cdn, "Publishes to", "API")
Rel(auth, user_db, "Manages credentials", "SQL")
Rel(user, user_db, "Stores profiles", "SQL")
Rel(video, video_db, "Stores metadata", "MongoDB")
Rel(analytics, analytics_db, "Stores metrics", "SQL")
Rel(auth, cache, "Sessions", "Redis")
Rel(video, cache, "Caches metadata", "Redis")
Rel(search, search_index, "Indexes & queries", "REST")
Rel(video, event_bus, "Publishes VideoUploaded", "Kafka")
Rel(analytics, event_bus, "Publishes ViewStarted", "Kafka")
Rel(recommendation, event_bus, "Consumes events", "Kafka")
Rel(search, event_bus, "Consumes events", "Kafka")
Best Practices
- Use appropriate level - Context for stakeholders, Container for architects, Component for developers
- Keep it focused - One system per Context diagram, one container per Component diagram
- Show key relationships - Don't clutter with every possible connection
- Use consistent naming - Same names across all diagram levels
- Add technology details - Specify frameworks, languages, protocols at Container/Component level
- Update regularly - Keep diagrams in sync with architecture
- Use boundaries - Group related containers/components logically
- Document protocols - Show communication methods (REST, gRPC, messaging)
- Highlight external systems - Use *_Ext variants for clarity
- Start simple - Begin with Context, drill down as needed
Common Architecture Patterns
Monolithic Application
C4Container
Person(user, "User")
Container_Boundary(system, "Application") {
Container(app, "Web Application", "Ruby on Rails", "Monolithic application")
ContainerDb(db, "Database", "PostgreSQL", "Application database")
ContainerDb(cache, "Cache", "Redis", "Session store")
}
Rel(user, app, "Uses", "HTTPS")
Rel(app, db, "Reads/writes", "SQL")
Rel(app, cache, "Caches", "Redis Protocol")
Three-Tier Architecture
C4Container
Person(user, "User")
Container_Boundary(presentation, "Presentation Tier") {
Container(web, "Web Server", "Nginx", "Static content")
Container(app, "App Server", "Node.js", "Application logic")
}
Container_Boundary(business, "Business Tier") {
Container(api, "API Server", "Java", "Business logic")
}
Container_Boundary(data, "Data Tier") {
ContainerDb(db, "Database", "MySQL", "Data storage")
}
Rel(user, web, "Uses", "HTTPS")
Rel(web, app, "Proxies to", "HTTP")
Rel(app, api, "Calls", "REST")
Rel(api, db, "Reads/writes", "SQL")
Event-Driven Architecture
C4Container
Person(user, "User")
Container(frontend, "Frontend", "React", "User interface")
Container(api, "API Gateway", "Kong", "API routing")
Container_Boundary(services, "Services") {
Container(order, "Order Service", "Java", "Order processing")
Container(inventory, "Inventory Service", "Go", "Stock management")
Container(notification, "Notification Service", "Node.js", "Alerts")
}
ContainerQueue(events, "Event Bus", "Kafka", "Event streaming")
ContainerDb(db, "Databases", "Various", "Service databases")
Rel(user, frontend, "Uses")
Rel(frontend, api, "Calls")
Rel(api, order, "Routes to")
Rel(order, events, "Publishes OrderCreated")
Rel(events, inventory, "Consumes events")
Rel(events, notification, "Consumes events")
Rel(order, db, "Persists")
Rel(inventory, db, "Persists")