📘 C4 Model: Drilling Down from Level 3 (Component) to Level 4 (Code) in Visual Paradigm

A practical tutorial for architects and developers to bridge structural design with implementation using PlantUML, reverse engineering, and focused modeling.

Introduction

Software architecture documentation often stalls at the Component level. Teams map out containers and components beautifully, but when developers open the IDE, they’re left guessing: How is this actually implemented? Where do the business rules live? How do these classes interact?

The C4 Model’s Level 4 (Code Diagram) solves this gap. It zooms into a single component to reveal the actual code structure—typically as a UML Class diagram, though ER diagrams or interface maps are also valid.

Unlike Levels 1–3, Level 4 is optional, selective, and volatile. It’s not meant to document every class or private method. Instead, it highlights the architecturally significant code: core domain entities, critical services, key interfaces, and the relationships that realize a component’s responsibility.

Who Should Use This?

• Developers & Tech Leads: Navigating complex modules, planning refactors, or reviewing PRs.
• Onboarding Engineers: Understanding implementation patterns without reading thousands of lines of code.
• Architects: Validating that component boundaries align with actual code organization.

When to Create Level 4 Diagrams?

✅ Complex business logic or domain models
✅ High-risk or frequently changing components
✅ Introducing new design patterns (CQRS, Strategy, Repository, DDD Aggregates)
✅ Technical discussions where class-level clarity prevents miscommunication

❌ Simple CRUD components, auto-generated DTOs, or utility classes
❌ Systems where the codebase is small and self-documenting

This tutorial walks you through a repeatable workflow in Visual Paradigm, provides ready-to-use PlantUML examples, and shares maintenance strategies to keep Level 4 diagrams valuable without becoming a documentation burden.

Guidelines & Core Principles

Before opening Visual Paradigm, internalize these rules to ensure your Level 4 diagrams stay useful:

💡 Rule of Thumb: If a class doesn’t help a developer understand where to add a feature or why a dependency exists, leave it out.

🔄 Step-by-Step Workflow in Visual Paradigm

Step 1: Preparation – Select & Analyze the Target Component

1. Open your Level 3 Component Diagram.
2. Identify the most critical component (e.g., Account Service, Payment Validator, Domain Model).
3. Ask:
   • What business rules or data flows does it encapsulate?
   • Which classes/interfaces drive its behavior?
   • Are there notable patterns (Repository, Gateway, Aggregate)?
4. Gather input from developers or skim the source code to confirm key elements.

Step 2: Create the Level 4 Diagram

🟢 Recommended: Sub-Diagram + Reverse Engineering

1. Right-click the target Component → Create Sub-Diagram → UML Class Diagram.
2. Use Visual Paradigm’s Reverse Engineering tool:
   • Tools > Code > Import Code
   • Select language (Java, C#, TypeScript, etc.) and source folder.
   • Choose only the package/module matching your component.
3. VP auto-generates classes, interfaces, enums, and relationships.

🔵 Alternatives:

• Manual Creation: Diagram > New > UML > Class Diagram. Drag elements from Model Explorer for consistency.
• AI-Assisted Drafting: Use VP’s AI Chatbot:
  "Generate a UML Class diagram for the AccountService component showing core entities, repositories, and gateway interfaces. Focus on public APIs and key dependencies."

Step 3: Build & Refine

• Trim the noise: Delete auto-generated DTOs, test classes, or framework annotations.
• Add stereotypes: «Service», «Repository», «Entity», «Gateway» for quick scanning.
• Simplify visibility: Show only architecturally relevant attributes/methods.
• Clarify relationships:
  • ───> Dependency
  • ───|> Generalization/Inheritance
  • ◆─── Composition
  • ○─── Aggregation
  • ..|> Realization (Interface)
• Add context notes: Explain orchestration, business rules, or external calls.
• Apply layout: Use Arrange > Auto Layout, group by package/layer, minimize crossings.

Step 4: Validate & Maintain

• Team walkthrough: “Does this match the current code? Where would you implement feature X?”
• Link to behavior: Pair with a Sequence or Activity diagram for runtime context.
• Update strategy: Regenerate via reverse engineering when major refactors occur. Edit manually only for architectural emphasis.
• Export & share: PNG/PDF for wikis, PlantUML for Git, or embed in Confluence/Jira.

🖼️ PlantUML Example: L3 Context → L4 Code Diagram

🔹 Level 3 Context (Brief Recap)

Container: API Application (Java + Spring Boot)
Component: Account Service (Orchestrates account operations, coordinates persistence & notifications)

🔹 Level 4 Code Diagram (PlantUML)

Copy-paste this into Visual Paradigm’s PlantUML editor, or any PlantUML renderer:

@startuml
title Level 4 Code Diagram: Account Service Component\n(Inside API Application – Spring Boot)

skinparam packageStyle rectangle
skinparam stereotypeCBackgroundColor #E8F4FD
skinparam classBackgroundColor #F0F7FF
skinparam classBorderColor #4A90D9
skinparam enumBackgroundColor #FFF4E6
skinparam enumBorderColor #FFA94D

package “Account Service Component” {

class AccountService {
– accountRepository: AccountRepository
– notificationGateway: INotificationGateway
+ getAccountSummary(customerId: String): AccountSummary
+ createTransaction(accountId: String, amount: BigDecimal, type: TransactionType): TransactionResult
+ transferFunds(fromAccount: String, toAccount: String, amount: BigDecimal): TransferResult
– validateTransaction(transaction: Transaction): void
}

interface INotificationGateway {
+ sendTransactionNotification(customerId: String, message: String): void
}

class AccountRepository {
+ findByCustomerId(customerId: String): List<Account>
+ findByAccountId(accountId: String): Optional<Account>
+ save(account: Account): Account
+ updateBalance(accountId: String, newBalance: BigDecimal): void
}

class Account {
– id: String
– customerId: String
– accountNumber: String
– balance: BigDecimal
– transactions: List<Transaction>
+ deposit(amount: BigDecimal): void
+ withdraw(amount: BigDecimal): void
+ getAvailableBalance(): BigDecimal
}

class Transaction {
– id: String
– accountId: String
– amount: BigDecimal
– type: TransactionType
– timestamp: LocalDateTime
– status: TransactionStatus
}

enum TransactionType {
DEPOSIT
WITHDRAWAL
TRANSFER
}

enum TransactionStatus {
PENDING
COMPLETED
FAILED
}
}

‘ Relationships
AccountService –> AccountRepository : uses
AccountService –> INotificationGateway : depends on
AccountService ..> Account : operates on
AccountService ..> Transaction : creates/manages

Account “1” *– “0..*” Transaction : contains
AccountRepository –> Account : manages

note right of AccountService
<b>Orchestrator</b>
Orchestrates account operations.
Applies business rules and
coordinates persistence + notifications.
end note

note bottom of Account
<b>Domain Entity</b>
Core domain entity with
encapsulated business methods.
end note

‘ Optional: Manual legend instead of SHOW_LEGEND
note as Legend
<b>Legend:</b>
–> Dependency
..> Association
*– Composition
—- Interface/Class
<i>Italic</i> = Abstract
end note

📊 How to Use This in Visual Paradigm

1. Paste & Render: Diagram > New > PlantUML Diagram, paste the code, click Render.
2. Convert to Native UML: Right-click the rendered diagram → Convert to UML for full VP editing, layout tools, and model repository sync.
3. Link as Sub-Diagram: Attach it under the Account Service component in your L3 diagram for automatic hierarchy navigation.
4. Version Control: Save the .puml file in your repo alongside code. Update when component contracts change.

💡 Tips, Tricks & Maintenance Strategies

Tooling & Workflow Tips

🔍 Relationship & Stereotype Cheat Sheet

' Common C4/UML mappings for Level 4
AccountService --> AccountRepository       : "Dependency (uses)"
AccountRepository ..|> JpaRepository       : "Realization/Inheritance"
Account "1" *-- "0..*" Transaction         : "Composition (owns lifecycle)"
AccountService --> INotificationGateway    : "Interface dependency"
class Account #LightGreen                  : "Stereotype/Color for Domain"
note right of AccountService               : "Architectural intent"

⚠️ Pitfalls to Avoid

• Over-detailing: Including private methods, getters/setters, or framework boilerplate. → Filter aggressively.
• Manual upkeep: Hand-drawing large class diagrams guarantees staleness. → Reverse engineer + refine.
• Losing context: Forgetting the parent Component boundary. → Always show the package/frame.
• Ignoring behavior: Class diagrams show structure, not flow. → Pair with Sequence diagrams.
• Inconsistent styling: Mixing C4 shapes with raw UML without a legend. → Define a team style guide.

🔄 Keeping Level 4 “Living”

1. Treat as on-demand documentation: Generate when needed for reviews, onboarding, or refactors.
2. Schedule sync points: Regenerate during major sprint releases or architecture spikes.
3. Link to ADRs: Attach Architecture Decision Records to explain why certain classes or patterns exist.
4. Automate where possible: CI/CD pipeline can generate PlantUML from code and publish to docs site.

🏁 Conclusion

Drilling from Component (Level 3) to Code (Level 4) completes the C4 hierarchy, transforming abstract architecture into actionable implementation guidance. When done right, Level 4 diagrams don’t just document code—they enable precise technical conversations, accelerate onboarding, and prevent architectural drift.

Key Takeaways

🔹 Selective over exhaustive: Focus on architecturally significant classes, not every file.
Reverse engineering is your friend: Generate from code, then curate for clarity.
🔹 Traceability matters: Keep the parent Component visible to maintain the C4 thread.
🔹 PlantUML + Visual Paradigm = Hybrid power: Version-controlled code-friendly syntax with enterprise-grade visual modeling.
Pair structure with behavior: Class diagrams show “what exists”; Sequence/Activity diagrams show “how it works”.

Level 4 diagrams are inherently volatile. Embrace that. Don’t strive for perpetual perfection—strive for timely clarity. Generate them when the team needs them, validate them with the people who write the code, and update them when the architecture shifts.

🚀 Your Next Step

1. Pick one critical component from your Level 3 diagram.
2. Reverse engineer its package in Visual Paradigm.
3. Trim to 5–15 key classes, add stereotypes & notes.
4. Share in a 15-minute team walkthrough: “Where would you add feature X based on this?”
5. Commit the PlantUML to your repo. Repeat per sprint.

“Architecture isn’t just about drawing boundaries—it’s about making the inside of those boundaries understandable.”

With this workflow, your C4 documentation stops being a static artifact and becomes a living navigation system for your codebase. Start small. Stay focused. Let the code guide the diagram.

🔗 Resources:

• C4 Model Diagrams Visual Paradigm Desktop
• PlantUML Class Diagram Syntax
• C4 Model Official Site
• AI-Powered C4 Diagram Studio

Build clearly. Document intentionally. Ship confidently. ️✨