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.

🎯 Stakeholder Focus

• Developers: Understanding internal module boundaries and dependencies.

• Architects: Ensuring proper layering and Separation of Concerns.

🛠 Folder Structure Mapping

Level 3 should ideally map to your folder structure:

• Controller/Handler: Maps to src/api , internal/handler .

• Service/Logic: Maps to src/services , internal/usecase .

• Repository/Data Access: Maps to src/db , internal/repository .

• Infrastructure Wrapper: Maps to pkg/email , src/adapters .

🚫 Anti-Patterns to Guard (Level 3)

• OVER-DETAILING: Don't draw every class. Only draw major logical groupings.

• MIXING CONTAINERS: Focus only on ONE container at a time.

• CIRCULAR DEPENDENCIES: Level 3 is the best place to identify and fix tight coupling.

🔍 Codebase Scanning (L3 Synthesis)

To identify components in a container, scan for:

• Folder Names: services/ , controllers/ , handlers/ , repositories/ , models/ .

• Project Structure Patterns: Layered architecture, Clean Architecture (Hexagonal), or Feature-based folders.

Mermaid Template (Enhanced C4Component)

C4Component title [Container Name] - Component Diagram

Container(spa, "Web App", "React/TS", "Single Page Application")

Container_Boundary(api_svc, "API Service") {
    Component(order_ctrl, "Order Handler", "Go Handler", "Handles incoming REST requests.")
    Component(order_svc, "Order Service", "Go Logic", "Processes business logic for orders.")
    Component(inv_repo, "Inventory Client", "Go Client", "Wraps calls to the Inventory system.")
    Component(db_repo, "Database Repository", "SQL Client", "Handles SQL queries for orders.")
}

ContainerDb(db, "Order Database", "PostgreSQL", "Stores orders.")

Rel(spa, order_ctrl, "Submits orders", "JSON/HTTPS")
Rel(order_ctrl, order_svc, "Calls logic", "Method call")
Rel(order_svc, inv_repo, "Checks stock", "Method call")
Rel(order_svc, db_repo, "Saves order", "Method call")
Rel(db_repo, db, "Writes", "SQL/TCP")

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?