# 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
```plantuml
@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
```plantuml
@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
```plantuml
@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

```mermaid
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