ADR 006: Use C4 Model for Architecture Documentation

Status

Accepted

Context

Architecture diagrams need to communicate at multiple levels of abstraction:

• System context (Level 1)
• Container level (Level 2)
• Component level (Level 3)
• Code level (Level 4 - optional)

Decision

Use the C4 Model methodology for all architecture documentation.

Consequences

Positive

• Hierarchical abstraction levels
• Clear stakeholder communication
• Tool-agnostic (can use Structurizr, Mermaid, PlantUML)
• Industry standard
• Forces clear thinking about boundaries

Negative

• Requires learning C4 notation
• Can be verbose for simple systems
• Multiple diagrams needed for full picture

C4 Levels

C1: System Context

C2: Container Level

C3: Component Level

(Detailed in TDD)

Mapping to Artifacts

C4 Level	Artifact	Audience
C1 - Context	SDD Section 2	Business stakeholders
C2 - Container	SDD Section 3, TDD Section 5	Architects
C3 - Component	TDD Section 4	Developers
C4 - Code	Source code	Developers

Alternatives Considered

Alternative	Pros	Cons
UML	Standard	Complex, verbose
ArchiMate	Enterprise focus	Heavyweight
Custom diagrams	Flexible	Inconsistent
No diagrams	Simple	Poor communication

Implementation

Use Mermaid for C4 diagrams (native GitHub support):

```mermaid
C4Context
    title System Context Diagram
    
    Person(user, "User", "Video content creator")
    System(pipeline, "Pipeline", "Video-to-Knowledge")
    System_Ext(youtube, "YouTube", "Video platform")
    
    Rel(user, pipeline, "Submits URL")
    Rel(pipeline, youtube, "Downloads")

## Notes
Generate all 3 levels (C1, C2, C3) for every artifact set. C4 is optional for simple components.