Distinguishing C4 containers from Docker containers
One of the most frequent points of confusion when people first encounter the C4 Model is the term “Container” — especially in 2025–2026, when nearly everyone associates “container” with Docker, Kubernetes, container images, and OCI runtimes.
The C4 Model uses the word Container in a completely different, higher-level, architectural sense — and it’s important to clearly separate the two concepts right from the start.
C4 Container: The Architectural / Logical Definition
In the C4 Model, a Container is:
A separately runnable or deployable unit of software that executes code or hosts data.
It represents a cohesive, bounded piece of the system that:
- Has its own distinct runtime/process boundary
- Can be developed, built, tested, deployed, scaled, monitored, and (in many cases) replaced somewhat independently
- Delivers a significant portion of the overall system’s responsibility
This is a logical / architectural abstraction, not tied to any specific deployment technology.
Examples of C4 Containers (regardless of how they are actually deployed):
- A Spring Boot REST API service
- A React single-page application (SPA) served from its own domain
- A native iOS or Android mobile app
- A PostgreSQL database instance (or schema logically separated for this system)
- A Kafka topic cluster used for event streaming
- An AWS Lambda function or group of related functions
- A background worker / scheduled batch job
- A third-party SaaS service treated as a black box (e.g., Stripe, Auth0)
Key characteristics at Level 2:
- Focus on responsibility, technology choice, and interaction style (HTTP, gRPC, JDBC, AMQP, etc.)
- No concern for pods, nodes, replicas, Helm charts, or container orchestration details yet
Docker / OCI Container: The Deployment / Runtime Definition
In the DevOps and cloud-native world, a container (lowercase, usually referring to Docker/OCI containers) is:
A standardized, lightweight, portable unit of software packaging and execution that includes code + dependencies + runtime environment, isolated via OS-level virtualization (namespaces, cgroups, etc.).
It is a deployment and runtime artifact:
- Built from a Dockerfile or similar
- Runs via Docker, containerd, Podman, CRI-O, etc.
- Orchestrated by Kubernetes, Docker Compose, ECS, Nomad, etc.
- Typically one process per container (following the “one process per container” best practice)
Examples:
- A Docker image running your Spring Boot JAR
- A containerized NGINX reverse proxy
- A PostgreSQL Docker container running the database server
Side-by-Side Comparison
| Aspect | C4 Container (Level 2) | Docker/OCI Container |
|---|---|---|
| Level of abstraction | Architectural / logical | Deployment / runtime |
| Purpose | Communicate high-level structure & technology choices | Package, distribute, and run software in isolation |
| Scope | Can span multiple physical containers / pods | One process / image instance |
| Technology-specific? | No — can be monolith, microservice, serverless, etc. | Yes — tied to container runtime standards |
| Examples | “Order Service (Java)”, “Mobile App (iOS)”, “Kafka Event Bus” | order-service:1.2.3, postgres:16, kafka-broker |
| Deployment detail | Not shown (deferred to Deployment Diagram) | Very specific (image tags, ports, volumes, etc.) |
| When you see it | In C4 Container Diagrams | In Dockerfile, Kubernetes manifests, CI pipelines |
Practical Rule of Thumb
- If you’re talking about architecture, responsibilities, communication protocols, and technology choices → you’re talking about C4 Containers.
- If you’re talking about images, Dockerfiles, pods, replicas, Helm values, or kubectl apply → you’re talking about Docker/OCI containers.
A single C4 Container might be deployed as:
- One Docker container
- Multiple replicas/pods
- A serverless function invocation
- A VM-based process
- Even part of a larger monolith JAR/WAR
The mapping between C4 Containers and actual runtime containers is many-to-many and belongs in the Deployment Diagram (one of the supporting views covered in Module 5), not the Container Diagram.
Why This Distinction Matters
Confusing the two leads to common modeling mistakes:
- Trying to show pods, replicas, or Kubernetes namespaces in a Level 2 Container Diagram (too low-level)
- Drawing one giant “Monolith” container when the monolith actually contains multiple logical deployable units
- Over-fragmenting into dozens of tiny containers just because each microservice has its own Docker image
By keeping C4 Container as a logical, responsibility-focused boundary, your Level 2 diagrams stay clean, focused, and useful for architecture communication — while leaving runtime/deployment details for the right level (Deployment view).
With this clear distinction in mind, you’re now ready to confidently identify and name the real C4 Containers inside your system — the major moving parts that make everything work.