C4 Container Diagrams: Microservices Architecture Examples

Container diagrams are the second level of the C4 model, showing the high-level technology choices and architectural building blocks within your system. For microservices architectures, container diagrams are particularly valuable as they clearly illustrate service boundaries and communication patterns.

What are C4 Container Diagrams?

Container diagrams zoom into a software system to show the major technology choices and how responsibilities are distributed. In microservices architectures, containers typically represent:

• Individual microservices
• Databases and data stores
• Message queues and event brokers
• API gateways and load balancers
• External systems and third-party services

Microservices Container Examples

E-commerce Platform Architecture

Here's how a typical e-commerce platform might look at the container level:

[Web Frontend] --> [API Gateway] --> [User Service]
                                  --> [Product Service]  
                                  --> [Order Service]
                                  --> [Payment Service]

[User Service] --> [User Database]
[Product Service] --> [Product Database]
[Order Service] --> [Order Database] 
[Payment Service] --> [Payment Provider API]

Key containers in this example:

• Web Frontend: React SPA serving customer interface
• API Gateway: Kong/Nginx handling routing and authentication
• User Service: Node.js microservice managing user accounts
• Product Service: Java Spring Boot service for product catalog
• Order Service: Python Django service handling order processing
• Payment Service: .NET Core service integrating with payment providers

Banking System Container Architecture

A more complex example showing a banking system's container-level architecture:

• Internet Banking Web App: Customer-facing portal
• Mobile Banking App: iOS/Android native applications
• Core Banking API: Central service orchestrating business logic
• Account Service: Manages account information and balances
• Transaction Service: Processes and records all transactions
• Notification Service: Handles email and SMS communications
• Mainframe Integration: Legacy system connector
• Customer Database: PostgreSQL cluster storing customer data
• Transaction Database: Time-series database for transaction history

Container Diagram Best Practices

1. Technology Stack Clarity

Always specify the technology stack for each container:

• Language/Framework: "Node.js Express API", "React SPA"
• Database Technology: "PostgreSQL", "Redis Cache", "MongoDB"
• Infrastructure: "Docker containers", "AWS Lambda functions"

2. Communication Protocols

Show how containers communicate:

• Synchronous: HTTP REST APIs, GraphQL
• Asynchronous: Message queues (RabbitMQ, Apache Kafka)
• Database: Direct database connections (when appropriate)

3. External Dependencies

Clearly distinguish between internal containers and external systems:

• Use different colors or shapes for external systems
• Group related containers visually
• Show data flow directions with arrows

Common Microservices Patterns in C4

API Gateway Pattern

[Client] --> [API Gateway] --> [Service A]
                           --> [Service B] 
                           --> [Service C]

The API Gateway acts as a single entry point, handling:

• Authentication and authorization
• Request routing and load balancing
• Rate limiting and monitoring
• Response aggregation

Event-Driven Architecture

[Service A] --> [Event Bus] --> [Service B]
                            --> [Service C]
                            --> [Service D]

Services communicate through events, enabling:

• Loose coupling between services
• Scalable processing of high-volume events
• Resilient system design

Database Per Service

[Service A] --> [Database A]
[Service B] --> [Database B]  
[Service C] --> [Database C]

Each microservice owns its data, providing:

• Service independence and autonomy
• Technology diversity (polyglot persistence)
• Clear data ownership boundaries

Integration with Other C4 Levels

Container diagrams work best when integrated with other C4 model levels. Start with a C4 context diagram to establish system boundaries, then use container diagrams to show the internal architecture.

For complex services, you can drill down further with component diagrams that show the internal structure of individual containers.

When documenting architectural decisions about your container architecture, integrate your diagrams with Architecture Decision Records to capture the reasoning behind your technology choices.

Creating Container Diagrams

Our C4 visualization tool provides specialized support for creating container diagrams with:

• Pre-built container templates for common microservices patterns
• Technology-specific icons and styling
• Automatic layout suggestions for complex architectures
• Export capabilities for documentation and presentations

For a comprehensive understanding of how container diagrams fit into the complete C4 methodology, see our complete C4 model guide.

Conclusion

Container diagrams are essential for communicating microservices architecture to both technical and non-technical stakeholders. They strike the right balance between high-level system understanding and implementation detail, making them invaluable for architecture documentation and team alignment.

By following these patterns and practices, your container diagrams will effectively communicate your microservices architecture and serve as living documentation that evolves with your system.