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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kinhluan
• Source: kinhluan/skills
• License: MIT

Install and usage instructions live in the source repository linked above.