C4 level3 component

C4 Level 3: Component Diagram & Folder Mapping

Level 3 focuses on the internal architecture of a single container, bridging the gap between high-level containers and low-level code. This is where architecture patterns (Clean, Hexagonal, Onion, Vertical Slice) become visible.

"A component is a grouping of related functionality behind a well-defined interface." — Simon Brown

---

🎯 Stakeholder Focus

Stakeholder	What they need from L3	Questions they ask
Developers	Module boundaries, where to add new code	"Where does the payment logic go?"
Tech Leads	Layering, Separation of Concerns	"Is our dependency direction correct?"
Architects	Design consistency, pattern adherence	"Are we following Clean Architecture?"
New Hires	Onboarding, codebase navigation	"How is this container organized?"

---

🏗️ Architecture Patterns & Component Mapping

Pattern 1: Layered Architecture (Traditional)

┌─────────────────────────────────────────┐
│  Presentation Layer                     │
│  ├─ Controller/Handler                  │
│  └─ DTO/ViewModel                       │
├─────────────────────────────────────────┤
│  Business Logic Layer                   │
│  ├─ Service                             │
│  └─ Domain Model (Entity, VO)           │
├─────────────────────────────────────────┤
│  Data Access Layer                      │
│  ├─ Repository                          │
│  └─ ORM/Data Mapper                     │
└─────────────────────────────────────────┘

Folder Mapping:

src/
├── api/              → Presentation (controllers, handlers)
├── services/         → Business Logic (application services)
├── domain/           → Domain Model (entities, value objects)
├── repositories/     → Data Access (repository interfaces + implementations)
└── dto/              → Data Transfer Objects

Pattern 2: Clean Architecture (Robert C. Martin)

         ┌─────────────┐
         │  Frameworks │  ← Outer: UI, DB, External APIs
         │  & Drivers  │
         └──────┬──────┘
                │ depends on
         ┌──────┴──────┐
         │  Interface  │  ← Adapters: Controllers, Presenters, Gateways
         │   Adapters  │
         └──────┬──────┘
                │ depends on
         ┌──────┴──────┐
         │  Use Cases  │  ← Application Business Rules
         │  (Services) │
         └──────┬──────┘
                │ depends on
         ┌──────┴──────┐
         │   Entities  │  ← Enterprise Business Rules (innermost)
         └─────────────┘

Dependency Rule: Dependencies point INWARD only. Inner circles know nothing about outer circles.

Folder Mapping (Go example):

internal/
├── domain/           → Entities (pure business logic, no dependencies)
│   ├── order.go
│   └── value_objects.go
├── usecase/          → Use Cases (application services)
│   ├── place_order.go
│   └── cancel_order.go
├── interface/        → Adapters (driven + driving)
│   ├── controller/   → HTTP handlers
│   ├── presenter/    → Response formatters
│   └── gateway/      → External API clients
└── infrastructure/   → Frameworks (DB, cache, message queue)
    ├── repository/   → DB implementations
    └── messaging/    → Event publishers

Pattern 3: Hexagonal Architecture (Ports & Adapters)

              ┌──────────────┐
    ┌─────────│   Driving    │─────────┐
    │         │   Adapters   │         │
    │  HTTP   │  (Primary)   │  CLI    │
    │ Handler │              │ Tool    │
    └────┬────┴──────────────┴────┬────┘
         │                        │
         │    ┌──────────────┐    │
         └───▶│   Application │◀───┘
              │   Core (Domain)│
              │               │
         ┌───▶│   Ports       │◀───┐
         │    └──────────────┘    │
    ┌────┴────┬──────────────┬────┴────┐
    │  DB     │   External   │ Message │
    │ Adapter │   API Client │ Queue   │
    │(Driven) │   (Driven)   │Adapter  │
    └─────────┴──────────────┴─────────┘
         Driven Adapters (Secondary)

Key Concepts:

• Port: Interface defining what the application needs (driven) or provides (driving)
• Adapter: Implementation of a port for a specific technology
• Domain: Pure business logic, zero external dependencies

Folder Mapping:

src/
├── application/          → Use cases, domain services
│   ├── port/
│   │   ├── in/          → Driving ports (interfaces app exposes)
│   │   └── out/         → Driven ports (interfaces app needs)
│   └── service/
├── domain/              → Entities, value objects, domain events
└── adapter/
    ├── in/              → Driving adapters (HTTP, CLI, messaging)
    │   ├── web/
    │   └── cli/
    └── out/             → Driven adapters (DB, external APIs)
        ├── persistence/
        └── external/

Pattern 4: Vertical Slice Architecture

src/
├── features/
│   ├── place_order/          → One folder per feature
│   │   ├── handler.go        → HTTP handler
│   │   ├── command.go        → CQRS command
│   │   ├── validator.go      → Input validation
│   │   ├── service.go        → Business logic
│   │   ├── repository.go     → Data access
│   │   └── dto.go            → Request/response types
│   │
│   ├── cancel_order/
│   │   ├── handler.go
│   │   ├── command.go
│   │   └── ...
│   │
│   └── list_orders/
│       ├── handler.go
│       ├── query.go          → CQRS query
│       └── ...
│
└── shared/                   → Cross-cutting concerns
    ├── middleware/
    ├── auth/
    └── logging/

Principle: Each feature is self-contained. No horizontal layers. Changes to "Place Order" only touch features/place_order/.

---

📝 Mermaid Templates

Template A: Layered Architecture (API Service)

C4Component
    title Component Diagram for API Service

    Container(spa, "Web App", "React/TS", "Customer SPA")

    Container_Boundary(api, "API Service") {
        Component(auth_ctrl, "Auth Controller", "Go Handler", "Handles login, registration, token refresh.")
        Component(order_ctrl, "Order Controller", "Go Handler", "Handles order CRUD operations.")

        Component(auth_svc, "Auth Service", "Go", "Validates credentials, generates JWTs.")
        Component(order_svc, "Order Service", "Go", "Business logic for order lifecycle.")
        Component(payment_svc, "Payment Service", "Go", "Orchestrates payment processing.")

        Component(auth_repo, "Auth Repository", "SQL Client", "User persistence.")
        Component(order_repo, "Order Repository", "SQL Client", "Order persistence.")
        Component(payment_client, "Payment Client", "HTTP Client", "Stripe API integration.")

        Component(jwt_util, "JWT Utility", "Go", "Token generation and validation.")
        Component(event_pub, "Event Publisher", "Go", "Publishes domain events.")
    }

    ContainerDb(db, "Database", "PostgreSQL", "Primary data store.")
    System_Ext(stripe, "Stripe", "Payment processing.")

    Rel(spa, auth_ctrl, "POST /login", "JSON/HTTPS")
    Rel(spa, order_ctrl, "POST /orders", "JSON/HTTPS")

    Rel(auth_ctrl, auth_svc, "Calls", "Method call")
    Rel(order_ctrl, order_svc, "Calls", "Method call")

    Rel(auth_svc, auth_repo, "Uses", "Method call")
    Rel(auth_svc, jwt_util, "Uses", "Method call")
    Rel(order_svc, order_repo, "Uses", "Method call")
    Rel(order_svc, payment_svc, "Uses", "Method call")
    Rel(payment_svc, payment_client, "Uses", "Method call")
    Rel(order_svc, event_pub, "Uses", "Method call")

    Rel(auth_repo, db, "Reads/Writes", "SQL/TCP")
    Rel(order_repo, db, "Reads/Writes", "SQL/TCP")
    Rel(payment_client, stripe, "API calls", "REST/HTTPS")

Template B: Clean Architecture (Go)

C4Component
    title Component Diagram — Clean Architecture (Order Service)

    Container(spa, "Web App", "React", "Customer UI")

    Container_Boundary(order_service, "Order Service (Clean Arch)") {
        Component(handler, "HTTP Handler", "Go", "Adapter: converts HTTP to use case input.")
        Component(presenter, "JSON Presenter", "Go", "Adapter: formats use case output.")

        Component(place_order_uc, "Place Order Use Case", "Go", "Application: orchestrates order creation.")
        Component(cancel_order_uc, "Cancel Order Use Case", "Go", "Application: handles cancellation.")

        Component(order_entity, "Order Entity", "Go", "Domain: order business rules.")
        Component(order_repo_intf, "Order Repository (Interface)", "Go", "Domain: port for persistence.")
        Component(payment_intf, "Payment Gateway (Interface)", "Go", "Domain: port for payments.")

        Component(order_repo_impl, "Order Repository (Impl)", "Go + SQL", "Infrastructure: PostgreSQL adapter.")
        Component(stripe_adapter, "Stripe Adapter", "Go + HTTP", "Infrastructure: Stripe API adapter.")
    }

    ContainerDb(db, "Order DB", "PostgreSQL")
    System_Ext(stripe, "Stripe API")

    Rel(spa, handler, "POST /orders", "JSON/HTTPS")
    Rel(handler, place_order_uc, "Invokes", "Method call")
    Rel(place_order_uc, order_entity, "Creates", "Method call")
    Rel(place_order_uc, order_repo_intf, "Saves via", "Interface")
    Rel(place_order_uc, payment_intf, "Charges via", "Interface")

    Rel(order_repo_intf, order_repo_impl, "Implemented by", "Dependency Injection")
    Rel(payment_intf, stripe_adapter, "Implemented by", "Dependency Injection")

    Rel(order_repo_impl, db, "SQL queries", "TCP")
    Rel(stripe_adapter, stripe, "API calls", "HTTPS")

---

🛠 Folder Structure Mapping by Language

Go (Clean Architecture)

internal/
├── domain/
│   ├── entity/
│   │   └── order.go
│   ├── valueobject/
│   │   └── money.go
│   └── event/
│       └── order_placed.go
├── usecase/
│   ├── place_order.go
│   └── cancel_order.go
├── adapter/
│   ├── in/
│   │   └── http/
│   │       └── order_handler.go
│   └── out/
│       ├── persistence/
│       │   └── order_repository.go
│       └── payment/
│           └── stripe_adapter.go
└── config/
    └── app.go

Python (Hexagonal / FastAPI)

src/
├── domain/
│   ├── models/
│   │   └── order.py
│   ├── value_objects/
│   │   └── money.py
│   └── events/
│       └── order_placed.py
├── application/
│   ├── ports/
│   │   ├── in/
│   │   │   └── order_use_case.py
│   │   └── out/
│   │       ├── order_repository.py
│   │       └── payment_gateway.py
│   └── services/
│       └── order_service.py
├── adapters/
│   ├── in/
│   │   └── web/
│   │       └── order_router.py
│   └── out/
│       ├── persistence/
│       │   └── sqlalchemy_order_repo.py
│       └── payment/
│           └── stripe_client.py
└── main.py

TypeScript (Vertical Slice / NestJS-style)

src/
├── features/
│   ├── orders/
│   │   ├── orders.module.ts
│   │   ├── place-order/
│   │   │   ├── place-order.handler.ts
│   │   │   ├── place-order.command.ts
│   │   │   └── place-order.dto.ts
│   │   ├── cancel-order/
│   │   │   └── ...
│   │   └── list-orders/
│   │       └── ...
│   └── payments/
│       └── ...
├── shared/
│   ├── decorators/
│   ├── filters/
│   └── guards/
└── main.ts

---

🚫 Anti-Patterns to Guard (Level 3)

Anti-Pattern	Symptom	Fix
Over-Detailing	Every class drawn	Only major logical groupings (5-15 components)
Mixing Containers	Components from multiple containers	Focus on ONE container per diagram
Circular Dependencies	A→B→C→A cycle	Refactor: extract shared interface, merge, or restructure
Anemic Components	Component with no clear responsibility	Rename to reflect single responsibility
Layer Violation	Domain imports infrastructure	In Clean/Hexagonal: domain must have zero external deps
God Component	One component handles everything	Split by responsibility or feature

---

🔍 Codebase Scanning (L3 Synthesis)

# Identify component boundaries by folder structure
find src -type d -maxdepth 2 | sort

# Look for architecture patterns
grep -r "interface\|abstract class\|port\|adapter" src/ --include="*.go" --include="*.ts" --include="*.py"

# Check dependency direction (domain should not import infrastructure)
# In Go: check go.mod or import paths
grep -r "infrastructure\|adapter\|external" internal/domain/ || echo "✅ Clean: domain has no infra imports"

# Find circular dependencies
# Go: use golang.org/x/tools/cmd/depgraph or go mod graph
# Python: use pipdeptree or import-linter
# TypeScript: use madge

---

✅ Level 3 Success Criteria

• Does the diagram map directly to the container's folder structure?
• Are internal interactions (method calls/internal events) clearly labeled?
• Is it clear how each component contributes to the container's responsibility?
• STRICT: Does it focus only on the zoomed-in container?
• STRICT: Are there ≤15 components?
• Does the dependency direction follow the chosen architecture pattern?
• Are circular dependencies identified and resolved?

---

🔄 From L3 to L4

L3 Signal	L4 Action
"This component has complex internal logic"	UML class diagram
"The data model is hard to understand"	ERD (Entity Relationship Diagram)
"New developers struggle with this module"	Document key classes and their relationships
"We need to refactor this component"	L4 reveals exact coupling points

Next: Use c4-level4-code for implementation details.

---

📚 References

• C4 Model — Component Diagram — Simon Brown
• Clean Architecture — Robert C. Martin
• Hexagonal Architecture — Alistair Cockburn
• Vertical Slice Architecture — Jimmy Bogard