When to Use Level 3

Judiciously applying component-level detail where it adds specific value for developers

The Component Diagram (Level 3) is the most optional of the core C4 levels — and deliberately so. Unlike System Context (almost always created) and Container Diagrams (created for the vast majority of systems), Level 3 should be applied selectively and only when it delivers clear, tangible value.

The guiding principle is simple:

Create a Component Diagram for a container only if the additional detail meaningfully helps developers (or other technical stakeholders) understand, maintain, evolve, or refactor that container.

If zooming to Level 3 doesn’t reduce confusion, speed up onboarding, highlight design problems, or guide important decisions — skip it. Over-modeling at this level creates maintenance overhead and dilutes the C4 Model’s lightweight philosophy.

Situations Where Level 3 Adds High Value (Strong Reasons to Create It)

1. Complex or large containers
   • Monolithic applications, legacy backends, or “big ball of mud” services where internal structure is not obvious from reading code or package structure.
   • Example: A 200k-line monolithic Spring Boot application with tangled business logic — a Component Diagram can reveal modular boundaries that are currently invisible.
2. Domain-heavy or business-critical containers
   • Microservices or modules that encapsulate significant domain logic (pricing engines, risk calculators, order orchestration, compliance workflows).
   • Here, Level 3 helps make domain concepts, bounded contexts, aggregates, and business rules explicit and communicable.
3. Monolith decomposition or microservices extraction initiatives
   • When planning to break a monolith into services, Level 3 diagrams are invaluable for identifying candidate bounded contexts, extractable modules, seams, and anti-corruption layers before any code is touched.
   • They become the shared blueprint during workshops and refactoring sprints.
4. Onboarding new developers to a complicated service
   • A new team member joining a team-owned microservice with 20+ packages and unclear responsibility boundaries benefits enormously from a one-page Component Diagram that says: “Here’s how the major logical pieces fit together — start here.”
5. Architecture reviews, threat modeling, or security audits
   • When you need to analyze internal coupling, dependency direction, trust boundaries, or sensitive data flows inside a container (e.g., where PII is handled, where authentication checks occur).
   • Component-level visibility exposes risks that Container-level diagrams hide.
6. Multiple teams working on the same container
   • In larger organizations, when different squads own different parts of one deployable unit (common in “modular monolith” or “micro-frontends + shared backend” setups).
   • Clear component boundaries and interfaces reduce cross-team coordination pain.
7. Applying domain-driven design (DDD) or clean architecture principles
   • When the team wants to visualize and enforce separation between domain core, application layer, infrastructure adapters, and anti-corruption layers.

Situations Where You Should Usually Skip Level 3 (Low or No Value)

• Simple, thin containers
  • A basic CRUD API with one controller, one service, one repository — nothing interesting to decompose.
  • A stateless proxy, gateway, or simple worker that delegates everything externally.
• Well-structured microservices with clear single responsibility
  • If the container already follows good modularity (small codebase, obvious package structure, one primary domain concept), Level 3 adds little beyond what’s already self-evident.
• Purely infrastructural or utility containers
  • Caches, message queues, file stores, monitoring agents — these rarely need internal decomposition.
• Early-stage prototypes or MVPs
  • When the architecture is still fluid and changing rapidly, investing in Level 3 can be premature.
• When no one is asking for it
  • If developers, architects, and stakeholders are already comfortable with the container’s internal workings (from code reading, pair programming, or existing docs), don’t create diagrams just because “it’s Level 3.”

Practical Decision Checklist

Before investing time in a Component Diagram, ask:

• Does the container’s internal complexity cause confusion, bugs, or slow onboarding today?
• Are we planning meaningful change (refactor, split, extract, redesign) in the next 6–12 months?
• Would a 30-minute drawing session save days or weeks of developer time later?
• Is there visible tight coupling, god-classes, or tangled logic that needs to be surfaced?
• Do multiple people need a shared, up-to-date mental model of this container’s internals?

If you answer “yes” to 2+ of these — create the diagram. If “no” to most — stay at Level 2 and revisit only when pain emerges.

Final Mindset

Level 3 is a precision tool, not a mandatory step. Use it judiciously, where it solves real problems for developers. When you do use it, keep diagrams focused, current, and — ideally — generated or at least versioned alongside code (e.g., via C4-PlantUML or Structurizr).

In the hands-on section ahead, you’ll practice deciding exactly when Level 3 is warranted: we’ll look at example containers, evaluate their complexity, and build Component Diagrams only for those where the extra detail clearly adds developer value — reinforcing this selective, value-driven approach.

This discipline keeps your C4 models lean, relevant, and truly useful — exactly as the model intends.