Using the C4 Model & PlantUML for Production-Grade Architecture Documentation
Executive Summary
This case study presents a detailed analysis of the live production deployment of a modern, high-performance e-commerce platform. Designed to serve thousands of concurrent users across web and mobile channels, the system leverages a microservices-inspired architecture with a focus on scalability, resilience, performance, and operational clarity.
The deployment is built around the C4 Model — specifically, the Deployment Diagram — using PlantUML and the C4-PlantUML standard library to model runtime containers mapped onto physical/virtual infrastructure. The architecture integrates polyglot backends (Java + Go), Redis caching, PostgreSQL primary/replica clustering, gRPC and HTTP/2 protocols, and Nginx-based load balancing.
Key outcomes:
-
Achieves 10,000+ requests per second at the API gateway.
-
Ensures high availability through database replication and fallback paths.
-
Optimizes performance via aggressive caching and protocol selection.
-
Enables developer agility with language-optimized services.
-
Supports cross-platform experiences (React SPA + React Native mobile).
This document demonstrates how the C4 Deployment Diagram serves as a living, version-controlled artifact that aligns technical teams, supports incident response, and guides capacity planning.
1. Business & Technical Context
Business Objectives
The e-commerce platform supports:
-
Real-time product browsing and search.
-
Dynamic inventory checks and pricing.
-
Secure, reliable order placement and checkout.
-
Seamless experiences across browsers and native mobile apps.
Target users: Global consumers expecting low-latency interactions, real-time updates, and zero downtime during peak events (e.g., Black Friday, seasonal sales).
Deployment Diagram Generated by Visual Paradigm AI Chatbot
PlantUML Code Generation by Visual Paradigm AI Chatbot
@startuml
!include https://static.visual-paradigm.com/plantuml-stdlib/C4-PlantUML/master/C4_Deployment.puml
title Deployment Diagram for E-Commerce Platform – Live
AddElementTag(“fallback”, $bgColor=”#c0c0c0″, $fontColor=”#666666″)
AddRelTag(“fallback”, $textColor=”#c0c0c0″, $lineColor=”#438DD5″)
Deployment_Node(deploymentnode_live, “E-Commerce Live”, “Live Production Environment”, “Production data center in Seattle”) {
AddProperty(“Location”, “Seattle, WA”)
AddProperty(“Network”, “High-speed fiber”)
Deployment_Node_L(deploymentnode_api_gateway, “api-gw-01”, “Ubuntu 22.04 LTS”, “API gateway for routing requests to backend services.”) {
AddProperty(“Traffic”, “10k+ requests/second”)
AddProperty(“Protocol”, “HTTP/2 and gRPC”)
Deployment_Node_L(deploymentnode_order_service, “Order Service”, “Java Spring Boot”, “Handles order creation, processing, and fulfillment.”) {
Container(container_order, “Order Management”, “Java and Spring Boot”, “Manages order lifecycle including creation, status updates, and delivery.”)
}
Deployment_Node_L(deploymentnode_product_service, “Product Service”, “Go with Gin”, “Provides product catalog and search functionality.”) {
Container(container_product, “Product Catalog”, “Go and Gin”, “Serves product details, pricing, and availability.”)
}
}
Deployment_Node_R(deploymentnode_db_primary, “db-prime-01”, “Ubuntu 22.04 LTS”, “Primary database server.”) {
Deployment_Node_R(deploymentnode_postgresql_primary, “PostgreSQL – Primary”, “PostgreSQL 15”, “Main database storing orders, products, and user data.”) {
ContainerDb(container_db_primary, “Database”, “PostgreSQL 15”, “Stores order history, inventory, and product catalog.”)
}
}
Deployment_Node_R(deploymentnode_db_secondary, “db-replica-02”, “Ubuntu 22.04 LTS”, “Secondary database server.”, $tags=”fallback”) {
Deployment_Node_R(deploymentnode_postgresql_secondary, “PostgreSQL – Secondary”, “PostgreSQL 15”, “Standby replica for failover.”, $tags=”fallback”) {
ContainerDb(container_db_secondary, “Database”, “PostgreSQL 15”, “Replica of primary database, used for read scaling and disaster recovery.”, $tags=”fallback”)
}
}
Deployment_Node_L(deploymentnode_cache_service, “cache-srv-01”, “Redis 7.0”, “Caching layer to reduce database load.”) {
Container(container_cache, “Cache Layer”, “Redis 7.0”, “Stores frequently accessed product and order data.”)
}
Deployment_Node(deploymentnode_web_server, “web-srv-01”, “Ubuntu 22.04 LTS”, “Frontend web server.”) {
AddProperty(“CORS”, “Enabled”)
AddProperty(“SSL”, “Enabled”)
Deployment_Node(deploymentnode_nginx, “Nginx”, “Nginx 1.25”, “Reverse proxy and load balancer.”) {
Container(container_frontend, “Frontend Application”, “React and Node.js”, “Delivers the shopping cart, product pages, and checkout experience.”)
}
}
}
Deployment_Node(deploymentnode_mobile_device, “Customer’s Mobile Device”, “iOS or Android”) {
Container(container_mobile_app, “Mobile App”, “React Native”, “Provides shopping, product browsing, and checkout functionality on mobile devices.”)
}
Deployment_Node(deploymentnode_customer_computer, “Customer’s Computer”, “Windows or macOS”) {
Deployment_Node(deploymentnode_browser, “Web Browser”, “Chrome, Safari, Edge”) {
Container(container_spa, “Single Page Application”, “React and Redux”, “Provides full e-commerce experience via web browser.”)
}
}
Rel(container_mobile_app, container_order, “Makes API calls to”, “gRPC”)
Rel(container_mobile_app, container_product, “Makes API calls to”, “gRPC”)
Rel(container_spa, container_order, “Makes API calls to”, “HTTP/2”)
Rel(container_spa, container_product, “Makes API calls to”, “HTTP/2”)
Rel(container_order, container_db_primary, “Reads from and writes to”, “JDBC”)
Rel(container_order, container_db_secondary, “Reads from and writes to”, “JDBC”, $tags=”fallback”)
Rel(container_product, container_db_primary, “Reads from and writes to”, “JDBC”)
Rel(container_product, container_db_secondary, “Reads from and writes to”, “JDBC”, $tags=”fallback”)
Rel(container_cache, container_db_primary, “Caches data from”, “Redis”)
Rel(container_cache, container_product, “Caches data from”, “Redis”)
Rel_R(container_db_primary, container_db_secondary, “Replicates data to”)
SHOW_LEGEND()
@enduml
Technical Requirements
| Requirement | Goal |
|---|---|
| Peak throughput | 10k+ RPS at the API gateway |
| Data consistency | ACID compliance for orders and inventory |
| High availability | 99.99% uptime SLA |
| Scalability | Horizontal scaling of services and databases |
| Performance | Sub-100ms response times for critical paths |
| Developer flexibility | Use optimal language per domain |
2. High-Level Deployment Structure
The live environment is logically partitioned into three tiers: Core Backend & Data, Data Persistence, and Frontend Delivery.
Core Backend & Data Tier (Left Side)
| Node | Technology | Function |
|---|---|---|
api-gw-01 (Ubuntu 22.04 LTS) |
Nginx 1.25 + gRPC/HTTP/2 proxy | Entry point for all client traffic; routes to Order and Product Services |
| Order Service | Java Spring Boot | Manages full order lifecycle: creation, payment processing, fulfillment, status tracking |
| Product Service | Go + Gin | Handles catalog management, product search, pricing, availability, and recommendations |
✅ Both services connect to the primary PostgreSQL instance via JDBC.
Caching Layer
| Node | Technology | Role |
|---|---|---|
cache-srv-01 |
Redis 7.0 | Caches hot product data, session states, and transient order information |
🔥 Performance Impact: Reduces database read load by up to 70% for product queries.
Data Persistence Tier (Right Side)
| Node | Technology | Purpose |
|---|---|---|
db-prime-01 |
PostgreSQL 15 (Primary) | Single source of truth for orders, inventory, users, and products |
db-replica-02 |
PostgreSQL 15 (Replica) | Read scaling and automatic failover; tagged “fallback” in diagram |
⚠️ Replication Mode: Synchronous streaming replication ensures data durability.
🔄 Failover: Manual or automated (via Patroni or similar) switch during primary failure.
Frontend Delivery Tier
| Node | Technology | Function |
|---|---|---|
web-srv-01 |
Nginx 1.25 (reverse proxy) | Serves React SPA with SSL/TLS termination, CORS policy enforcement, and load balancing |
🌐 Clients:
Web: Browser-based SPA using HTTP/2 (header compression, multiplexing).
Mobile: React Native app using gRPC (efficient binary protocol, strong typing).
3. Key Interactions & Data Flows
Client-to-Service Communication
| Client Type | Protocol | Reason |
|---|---|---|
| Mobile App | gRPC | Efficient binary encoding, reduced payload size, better battery usage |
| Web Browser | HTTP/2 | Native browser support, multiplexing, server push capabilities |
🔄 gRPC is used for mobile-specific APIs (e.g., checkout flow, cart updates).
Service-to-Database Interaction
-
Primary Path: All write operations and critical reads go to
db-prime-01. -
Read Scaling: Non-critical reads (e.g., product details, catalog views) are routed to
db-replica-02via connection pooling logic. -
Fallback Path: During primary failure, services can switch to
db-replica-02(tagged as “fallback” in the diagram).
📌 Note: Writes remain single-leader — no write splitting to replica.
Caching Strategy
-
Redis Cache Keys:
-
product:12345:details→ Cached for 5 minutes -
inventory:12345→ TTL: 30 seconds -
cart:session:abc123→ Session-specific, expires after 1 hour
-
-
Cache Invalidation:
-
Triggers on product update, stock change, or order completion.
-
Implemented via message queues (e.g., Kafka) or direct DB triggers.
-
⚠️ Trade-off: Eventual consistency — slight delay between DB update and cache sync.
Replication & Failover
-
Primary → Replica: Continuous WAL (Write-Ahead Log) streaming.
-
Failover Trigger: Health checks every 5 seconds; automated via orchestrator (e.g., Patroni).
-
Recovery Time: ~30–60 seconds to promote replica and redirect traffic.
🧩 Visual Cues: The “fallback” tag and grayed-out styling in the diagram emphasize that this is a non-primary path under normal conditions.
4. Key Architectural Decisions & Trade-offs
| Decision | Rationale | Trade-off / Consideration |
|---|---|---|
| Polyglot Backends (Java + Go) | Spring Boot offers mature transaction support and ecosystem for order processing. Go + Gin delivers high throughput and low latency for product search. | Increased operational complexity: two runtime environments, build pipelines, monitoring stacks. |
| Primary + Replica PostgreSQL | Ensures ACID compliance for financial data. Replication enables read scaling and disaster recovery. | Single write leader creates potential bottleneck during extreme write spikes. |
| Redis Caching Layer | Offloads frequent product reads; reduces DB load and improves latency. | Cache invalidation is complex; requires careful design to avoid stale data. |
| gRPC (mobile), HTTP/2 (web) | gRPC is ideal for mobile (smaller payloads, faster parsing). HTTP/2 is universally supported in browsers. | Dual protocol stack increases development and testing overhead. |
| Nginx Reverse Proxy | Centralizes SSL termination, load balancing, CORS, and rate limiting. | Adds a single point of failure (SPOF) unless deployed in HA mode. |
| Tagged Fallback Nodes | Clearly indicates failover paths for incident analysis and onboarding. | Requires discipline to keep diagrams updated during infrastructure changes. |
5. Non-Functional Properties Emphasized
| Property | How It’s Achieved |
|---|---|
| Performance | High-throughput Go service, Redis caching, gRPC efficiency, HTTP/2 multiplexing |
| Availability | Database replication, fallback paths, redundant nodes |
| Scalability | Read scaling via replica, potential for horizontal scaling of services |
| Observability | Clear protocols, traffic volume indicators, node locations, and tags |
| Security | SSL/TLS enforced, CORS policies applied, secure database connections |
| Maintainability | C4 diagrams are version-controlled, self-documenting, and aligned with codebase |
💡 These properties are not assumed — they are explicitly designed into the deployment structure.
6. C4 Model Alignment & Key Concepts Illustrated
This deployment diagram is a canonical example of a C4 Deployment Diagram, one of the four levels in the C4 Model (Context, Container, Component, Deployment).
✅ Core C4 Deployment Diagram Concepts Demonstrated
| Concept | Implementation in This Diagram |
|---|---|
| Deployment Nodes | Physical/virtual servers (api-gw-01, db-prime-01, etc.) |
| Container Instances | Runtime services (Order Service, Product Service, Redis, PostgreSQL) placed inside nodes |
| Infrastructure Nodes | Implied load balancer (Nginx), high-speed fiber network, data center location |
| Relationships | Directional arrows showing traffic flow, protocols (HTTP/2, gRPC, JDBC, Redis), and fallback logic |
| Tags & Styling | "fallback" tag and grayed-out style for db-replica-02 to indicate secondary role |
| Properties | OS versions, software versions, protocols, traffic volume, security settings |
| Environment Focus | Explicitly labeled as “Live Production Environment” |
🛠️ C4 Best Practices Followed
-
Mapping containers to infrastructure, not re-creating component logic.
-
Nested structure: Server → Runtime → Container (e.g.,
api-gw-01→ Spring Boot → Order Service). -
Explicit failover and scaling paths shown visually.
-
Protocols and technologies clearly labeled.
-
Visual cues (color, tags) used to distinguish primary vs. fallback paths.
-
Metadata-rich — includes location, version, and performance context.
📌 Why This Matters: This diagram answers the critical question:
“Where and how is this system actually running in production?”
It complements higher-level diagrams (e.g., Container Diagram showing service boundaries) by grounding them in real-world infrastructure.
7. Conclusion & Future Roadmap
✅ Summary of Successes
-
The platform delivers high performance, resilience, and developer flexibility.
-
The C4 Deployment Diagram acts as a living documentation artifact, integrated into CI/CD and version control.
-
Teams use it for:
-
Onboarding new engineers
-
Incident response and root cause analysis
-
Capacity planning and scaling decisions
-
Architecture reviews and compliance checks
-
🔮 Future Enhancements
| Enhancement | Benefit |
|---|---|
| Add Kubernetes Orchestration | Enables auto-scaling, self-healing, and declarative deployment |
| Introduce Database Sharding | Scales beyond single-primary limits for massive datasets |
| Add Observability Nodes | Include Prometheus, Grafana, and OpenTelemetry exporters for full-stack monitoring |
| Create Staging/Pre-Prod Diagrams | Enables environment-specific validation and change management |
| Automate Diagram Generation | Use AI tools (e.g., Visual Paradigm’s C4 PlantUML Studio) to generate diagrams from code or requirements |
🤖 AI-powered tools like Visual Paradigm’s C4 PlantUML Studio can generate these diagrams from natural language descriptions, accelerating documentation and reducing errors.
Reference List (Markdown Format)
- Visual Paradigm AI Diagram Generator: Complete C4 Model Support
Release notes highlighting AI-driven C4 model generation, including System Landscape, Context, Container, and Component diagrams. - About the C4 Diagrams in AI-Powered C4 PlantUML Studio
Comprehensive overview of how AI generates C4 diagrams, including prompt engineering, output validation, and enterprise use cases. - AI C4 System Landscape Diagram Generator – Visual Paradigm Guide
Step-by-step tutorial on generating a System Landscape diagram from a natural language input. - Visual Paradigm C4 PlantUML Studio Features
Official feature page detailing AI generation, PlantUML integration, multi-level diagram support, and collaboration tools. - Beginner’s Guide to C4 Model Diagrams
Accessible introduction to the four levels of the C4 Model and their practical applications. - The Ultimate Guide to C4 PlantUML Studio – Revolutionizing Software Architecture Design
Deep dive into how AI-assisted architecture design transforms workflows for teams of all sizes. - C4 Component Diagram: A Definitive Guide to Your Code’s Internal Structure
Reinforces the hierarchical nature of C4 diagrams, starting from the System Landscape down to Component-level detail.
Final Thoughts
This e-commerce platform exemplifies how modern software architecture can be clearly communicated, operationally effective, and future-proof — all through disciplined use of the C4 Model and PlantUML.
By treating deployment diagrams as living, version-controlled assets, organizations can:
-
Reduce onboarding time
-
Accelerate incident response
-
Align technical and business stakeholders
-
Evolve systems with confidence
🏁 The future of architecture documentation is not just visual — it’s intelligent, automated, and integrated.
With tools like C4 PlantUML Studio, teams can move from static diagrams to dynamic, AI-augmented architecture storytelling — ensuring clarity, consistency, and continuity across the software lifecycle.
📌 This case study is a practical reference for any team building or documenting production-grade systems using the C4 Model. Adapt it, extend it, and keep it alive with your code.