Skip to content
Home / Skills / Documentation / Architecture Documentation
DO

Architecture Documentation

Documentation core v1.0.0

Architecture Documentation

Overview

Architecture documentation captures the structural decisions, component relationships, data flows, and deployment topology of a software system. It uses standardized diagram notations (C4 Model, Mermaid) and written narratives to communicate the “big picture” to developers, architects, and stakeholders. In the full-lifecycle pipeline, @documentation-writer generates architecture docs in Phase 12 from the system design artifacts produced by @architect in Phase 3.

Key Concepts

C4 Model Levels

LevelNameAudienceShows
L1System ContextEveryoneSystem + external actors/systems
L2ContainerArchitects + DevsApplications, databases, message brokers
L3ComponentDevelopersClasses/modules within a container
L4CodeDevelopersClass diagrams (usually auto-generated)

Architecture Document Structure

docs/architecture/
├── overview.md              → System context + key decisions
├── containers.md            → Service boundaries + interactions
├── data-architecture.md     → Data stores, schemas, flows
├── infrastructure.md        → Cloud topology, networking
├── security-architecture.md → Auth, encryption, compliance
├── diagrams/
│   ├── system-context.mmd   → L1 Mermaid diagram
│   ├── container.mmd        → L2 Mermaid diagram
│   └── sequence/
│       ├── order-flow.mmd
│       └── auth-flow.mmd
└── adr/                     → Architecture Decision Records
    ├── template.md
    ├── 001-microservices.md
    └── 002-event-driven.md

Best Practices

  1. Start with C4 Level 1 — System context diagram is the most valuable single diagram
  2. Use Mermaid for diagrams — Renders in GitHub, versioned with code, no external tools
  3. Document decisions, not just structure — ADRs explain why the architecture is this way
  4. Keep diagrams current — Stale diagrams are worse than no diagrams
  5. Show data flows — Sequence diagrams for critical workflows
  6. Include NFR mapping — Show how architecture addresses scalability, security, reliability
  7. Layered documentation — Don’t show everything in one diagram; use C4 levels
  8. Link to implementation — Reference actual service repos, API specs, deployment configs

Code Examples

✅ Good: System Context Diagram (Mermaid)

graph TB
    subgraph "External Systems"
        PaymentGW["Payment Gateway<br/>(Stripe)"]
        EmailSvc["Email Service<br/>(SendGrid)"]
        IDV["Identity Verification<br/>(Jumio)"]
    end
    
    subgraph "Users"
        Customer["Customer<br/>(Web/Mobile)"]
        Agent["Support Agent<br/>(Internal)"]
        Admin["Administrator<br/>(Internal)"]
    end
    
    subgraph "KYC Platform"
        System["KYC Platform<br/>(Spring Boot + React)"]
    end
    
    Customer -->|"Submit KYC application"| System
    Agent -->|"Review applications"| System
    Admin -->|"Configure rules"| System
    System -->|"Process payments"| PaymentGW
    System -->|"Send notifications"| EmailSvc
    System -->|"Verify identity"| IDV

✅ Good: Container Diagram (Mermaid)

graph TB
    subgraph "KYC Platform"
        UI["React SPA<br/>(TypeScript)"]
        API["API Gateway<br/>(Spring Cloud Gateway)"]
        UserSvc["User Service<br/>(Spring Boot)"]
        KYCSvc["KYC Service<br/>(Spring Boot)"]
        NotifSvc["Notification Service<br/>(Spring Boot)"]
        
        UserDB[("User DB<br/>(PostgreSQL)")]
        KYCDB[("KYC DB<br/>(PostgreSQL)")]
        Cache[("Cache<br/>(Redis)")]
        MQ["Message Broker<br/>(Kafka)"]
    end
    
    UI --> API
    API --> UserSvc
    API --> KYCSvc
    UserSvc --> UserDB
    UserSvc --> Cache
    KYCSvc --> KYCDB
    KYCSvc -->|"publish events"| MQ
    MQ -->|"consume events"| NotifSvc

✅ Good: Sequence Diagram for Critical Flow

sequenceDiagram
    participant C as Customer
    participant UI as React UI
    participant API as API Gateway
    participant KYC as KYC Service
    participant DB as PostgreSQL
    participant K as Kafka
    participant N as Notification Service
    
    C->>UI: Submit KYC Application
    UI->>API: POST /api/v1/kyc/applications
    API->>KYC: Forward request
    KYC->>DB: INSERT application (status=PENDING)
    KYC->>K: Publish KYC_SUBMITTED event
    KYC-->>API: 201 Created
    API-->>UI: Application ID
    UI-->>C: "Application submitted"
    
    K->>N: Consume KYC_SUBMITTED
    N->>C: Send confirmation email

❌ Bad: Architecture Anti-Patterns

## Architecture
We use microservices. 
See the code for details.
(No diagrams, no decisions, no structure)

Anti-Patterns

  1. No diagrams — Text-only architecture descriptions are hard to follow
  2. One giant diagram — Shows everything; conveys nothing (use C4 levels)
  3. Diagrams in binary tools — Visio/Lucidchart files can’t be version-controlled
  4. Missing data flows — Static structure without showing how data moves
  5. No ADRs — Architecture decisions undocumented; context lost when people leave
  6. Over-documentation — 50-page architecture doc nobody reads (keep it scannable)

Testing Strategies

  • Diagram rendering — CI validates Mermaid diagrams render without errors
  • Consistency checks — Service names in diagrams match actual repo/service names
  • Link validation — All references to repos, APIs, docs are valid links
  • Review cadence — Architecture review quarterly; update docs if drift detected

References