ISA-Frontend/.claude/skills/architecture-documentation/references/c4-model.md

C4 Model Reference

Overview

The C4 model provides a way to visualize software architecture at four levels of abstraction:

1. Context - System landscape
2. Container - Applications and data stores
3. Component - Internal structure
4. Code - Class/module detail (optional)

Level 1: System Context Diagram

Shows the system under design and its relationships with users and external systems.

PlantUML Template

@startuml C4_Context
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

LAYOUT_WITH_LEGEND()

title System Context Diagram - ISA Frontend

Person(user, "Store Employee", "Uses the ISA application")
Person(admin, "Administrator", "Manages system configuration")

System(isa, "ISA Frontend", "Angular application for in-store operations")

System_Ext(backend, "ISA Backend", "REST API services")
System_Ext(auth, "Auth Provider", "Authentication service")
System_Ext(printer, "Printer Service", "Receipt/label printing")

Rel(user, isa, "Uses", "Browser")
Rel(admin, isa, "Configures", "Browser")
Rel(isa, backend, "API calls", "HTTPS/JSON")
Rel(isa, auth, "Authenticates", "OAuth2")
Rel(isa, printer, "Prints", "WebSocket")

@enduml

Key Elements

• Person: Human users of the system
• System: The system being documented (highlighted)
• System_Ext: External systems the system depends on
• Rel: Relationships between elements

Level 2: Container Diagram

Shows the high-level technology choices and how containers communicate.

PlantUML Template

@startuml C4_Container
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

LAYOUT_WITH_LEGEND()

title Container Diagram - ISA Frontend

Person(user, "Store Employee")

System_Boundary(isa, "ISA Frontend") {
    Container(spa, "SPA", "Angular 20", "Single-page application")
    Container(pwa, "Service Worker", "Workbox", "Offline capability")
    ContainerDb(storage, "Local Storage", "IndexedDB", "Offline data cache")
}

System_Ext(api, "ISA API Gateway")
System_Ext(cdn, "CDN", "Static assets")

Rel(user, spa, "Uses", "Browser")
Rel(spa, pwa, "Registers")
Rel(pwa, storage, "Caches data")
Rel(spa, api, "API calls", "REST/JSON")
Rel(spa, cdn, "Loads assets", "HTTPS")

@enduml

Container Types

• Container: Application or service
• ContainerDb: Database or data store
• ContainerQueue: Message queue

Level 3: Component Diagram

Shows the internal structure of a container.

PlantUML Template

@startuml C4_Component
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml

LAYOUT_WITH_LEGEND()

title Component Diagram - OMS Feature Module

Container_Boundary(oms, "OMS Feature") {
    Component(list, "Order List", "Angular Component", "Displays orders")
    Component(detail, "Order Detail", "Angular Component", "Order management")
    Component(store, "Order Store", "NgRx Signal Store", "State management")
    Component(api, "Order API Service", "Angular Service", "API communication")
}

ContainerDb_Ext(backend, "OMS Backend API")

Rel(list, store, "Reads state")
Rel(detail, store, "Reads/writes state")
Rel(store, api, "Fetches data")
Rel(api, backend, "HTTP requests")

@enduml

ISA-Frontend Domain Components

Suggested Component Structure

libs/[domain]/
├── feature/           → Component diagrams
│   └── [feature]/
├── data-access/       → Store/API components
│   └── [store]/
├── ui/                → Presentational components
│   └── [component]/
└── util/              → Utility components
    └── [util]/

Domain Boundaries

• CRM: Customer management, loyalty
• OMS: Order management, returns
• Checkout: Payment, transactions
• Remission: Product returns processing
• Catalogue: Product information

Mermaid Alternative

C4Context
    title System Context - ISA Frontend

    Person(user, "Store Employee", "Daily operations")

    System(isa, "ISA Frontend", "Angular SPA")

    System_Ext(backend, "Backend Services")
    System_Ext(auth, "Auth Service")

    Rel(user, isa, "Uses")
    Rel(isa, backend, "API calls")
    Rel(isa, auth, "Authenticates")

Best Practices

1. One diagram per level - Don't mix abstraction levels
2. Consistent naming - Use same names across diagrams
3. Show key relationships - Not every possible connection
4. Include legends - Explain notation
5. Keep it simple - 5-20 elements per diagram max