mirror of
https://dev.azure.com/hugendubel/ISA/_git/ISA-Frontend
synced 2025-12-28 22:42:11 +01:00
a2b29c0525
Move architecture documentation generation from a slash command to a skill with comprehensive reference materials (C4 model, Arc42, ADR templates).
164 lines
4.7 KiB
Markdown
164 lines
4.7 KiB
Markdown
# 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
|