Skip to content
March 30, 2026

A Better Way to Explain Modern Architecture Using the C4 Model

rajeshsgr · 5 min read · General IT Stuff, System Design

When we start building a complex system, the first thing we usually reach for is an architecture diagram. It helps us align early. A few boxes, some arrows, and suddenly everyone feels oriented. It gives us confidence that we’re building the right thing, in roughly the right way.

Then the system grows.

New services appear. Databases split. Queues are added. External APIs creep in. Eventually, an LLM and a vector database show up. The diagram grows along with the system, and before we realize it, what once created clarity has turned into a spaghetti of boxes and arrows.

The diagram still exists — but it no longer explains the system.

Architects can usually decode it, but explaining it to a product manager, a new dev, or a DevOps engineer becomes difficult. We zoom in, zoom out, redraw, or rely on verbal explanations to bridge the gaps. At that point, the problem isn’t how the system works — it’s how we communicate it.

That’s when it becomes clear that architecture diagrams are not about beautiful boxes. Their real purpose is communication.

The Problem: The “All-in-One” Map

To understand a city, you don’t start with a diagram that shows every pipe, wire, and brick. You begin with a world map, then zoom into a country, a city, and finally a street.

Traditional architecture diagrams try to show the pipes and the world map on the same page. Database schemas sit next to user flows. Tiny React components are drawn beside massive AWS regions. The scale breaks. The result is a document that’s too detailed for a product manager and still too vague for a lead developer.

What the C4 Model Actually Changes

The C4 model, created by Simon Brown, is based on a simple but powerful idea: instead of one diagram, use multiple diagrams, each with a clearly defined level of abstraction and a clearly defined audience.

The Four C’s:

C4 stands for Context, Container, Component, and Code. Each level answers a different question. The most important rule is also the easiest to break: never mix these levels in the same diagram

  1. Context: The “elevator pitch” view

Audience: Everyone (Stakeholders, Product Managers, Users). This diagram shows your system as a single box. It focuses on the who and the what. Who is using the system? What external systems (like an LLM provider) does it talk to? It ignores all technical implementation details.

2. Containers: The “infrastructure planning” view

Audience: Architects, Developers, DevOps. Now we zoom in. A “Container” is a separately deployable unit. This is where we see your modern tech stack in action. We show the Web App, the Microservices, the SQS Queues, the Relational DB, and the Vector DB. It shows how data flows between these major high-level blocks.

3. Components: The “development team” view

Audience: Developers. Zooming into one specific microservice — let’s say the AI Query Service — we see its internal components. We see the Embedding Generator, the Vector Retriever, and the LLM Prompt Builder. This helps a developer understand the internal responsibilities of the code.

4. Code: The “implementation” view (optional)

Audience: Developers. This is the level of classes and objects. In the modern world, we rarely draw this manually; we usually let the code be the source of truth or auto-generate it if needed.

Example

Think of a GenAI-enabled web application where users search, ask questions, and manage domain data (e.g., cases, tickets, knowledge articles). The UI calls an API gateway that routes requests to multiple microservices: a core domain service that persists transactional data in a relational database, an ingestion service that consumes documents and events asynchronously via SQS, and a RAG/AI service that generates embeddings, performs semantic retrieval from a vector database, and calls an external LLM to produce grounded answers. Async workers handle heavy jobs such as document chunking, embedding generation, and background enrichment, while observability and security controls capture logs/metrics/traces and enforce authentication/authorization across services.

C4 Level 1 — System Context Diagram

C4 Level 2— Container Diagram

C4 Level 3 — Component Diagram (RAG Services )

This Level-3 diagram zooms into the RAG service to show its key internal components and how they collaborate to retrieve context, construct prompts, and interact with an external LLM to generate responses.

How it Solves the Communication Crisis

By separating your architecture into these levels, you address different personas without causing confusion:

  • The Product Manager stays at Level 1. They understand the “Big Picture” and how the LLM adds value.
  • The Security Reviewer looks at Level 2. They can see exactly where the Vector DB sits and how SQS handles data transit.
  • The New Junior Developer looks at Level 3. They can see the specific component they need to modify to improve LLM prompt accuracy.

What C4 Doesn’t Try to Do

C4 doesn’t replace every architectural artifact. It doesn’t describe runtime behavior in detail. It doesn’t model infrastructure topology or network security rules. It doesn’t eliminate the need for sequence diagrams or ADRs.

What it does is provide a stable structural backbone — a shared mental model that other diagrams can hang off.

Conclusion

Architecture diagrams shouldn’t be a source of “spaghetti” stress. By using the C4 model, you create a navigable atlas of your system. You stop explaining “what the diagram fails to communicate” and start letting the maps speak for themselves.

Tags: , , , , ,

Leave a Reply