architecture-documentation

What this skill does

# Architecture Documentation

## Overview

Generates in-depth technical architecture documentation from codebases. Produces engineer-focused documentation with system diagrams, data flow analysis, component deep dives, and architectural decision rationale.

**Core principle:** Depth over breadth. Technical rigor over high-level summaries.

## When to Use

- User provides a codebase and asks for architecture documentation
- User requests system design documentation
- User needs technical documentation for handoff or onboarding
- User asks to document architectural decisions
- User needs diagrams showing system structure and data flow

## Workflow Checklist

Copy this checklist and check off items as you complete them:

```
Architecture Documentation Progress:
- [ ] Phase 1: Codebase exploration (structure, entry points, dependencies)
- [ ] Phase 2: Components identified (services, modules, databases)
- [ ] Phase 3: Data flow traced (request lifecycle, transformations)
- [ ] Phase 4: Business context extracted (README, comments, code)
- [ ] Phase 5: Documentation generated following structure below
- [ ] Phase 6: Diagrams created (PlantUML via Kroki, Mermaid, and/or Eraser syntax)
- [ ] Phase 7: Engineering analysis complete (all "why" questions answered)
- [ ] Phase 8: Quality validation passed
```

## Document Structure

Follow this structure (see example-output.pdf for full reference):

### Required Sections

1. **Abstract**
   - Formal research paper abstract after table of contents
   - Delineates system purpose, architecture approach, key technologies
   - Written in formal tone

2. **Context & Scope**
   - Business goals, stakeholders
   - System context diagram (PlantUML via Kroki)

3. **Architecture Constraints & Principles**
   - Why this approach? Immutable rules

4. **High-Level Architecture**
   - Container diagram showing major components
   - Data flow walkthrough with transformations (Input → Output at each stage)

5. **Component Deep Dives**
   - **Component Responsibility Matrix:** Table summarizing all components (see template below)
   - **Individual Component Sections** (repeat for each component):
     - **Purpose:** One sentence
     - **Implementation Details:** Stack, algorithms, dependencies (with WHY chosen)
     - **Engineering Analysis:** Trade-offs, configuration rationale, edge cases
     - Component diagram if complex

6. **Cross-Cutting Concerns**
   - Observability (logging, metrics, tracing)
   - Failure modes & recovery
   - Deployment & infrastructure

7. **Decision Log (ADRs)**
   - Major decisions with context and consequences

### Optional Appendices

**Appendix A: Technology Stack Summary**
- Table organized by category (Backend, AI/ML, Data Storage, Infrastructure, etc.)
- Columns: Technology | Version | Purpose | Architectural Layer
- Quick reference for all technologies used

**Appendix B: API Endpoint Reference**
- Complete endpoint documentation
- For each endpoint: Method, Path, Auth requirements, Request/Response schemas
- Include streaming event types if applicable
- Error response codes and formats

**Template format:**
```markdown
## 4. Component Deep Dives

### Component Responsibility Matrix

| Component | Primary Responsibility | Key Dependencies | Input/Output | Failure Modes | Recovery Strategies |
|-----------|----------------------|------------------|--------------|---------------|--------------------|
| [Name] | What it does (1 sentence) | Services/DBs it needs | What goes in → What comes out | How it breaks | How it recovers |
| [Name] | ... | ... | ... | ... | ... |

### 4.1 [Component Name]
[PlantUML diagram of internal logic]

**Purpose:** One sentence summary.

**Implementation Details (The "How"):**
- **Stack:** Technologies used
- **Key Algorithms:** How does it work?
- **Dependencies:** Libraries/services with citation (why chosen over alternatives)

**Engineering Analysis (The "Why"):**
- **Trade-offs:** Why this approach? What was rejected and why?
- **Configuration:** Why these specific settings? (timeouts, limits, buffer sizes)
- **State Management:** Stateless or stateful? Where persisted? How consistent?
- **Edge Cases:** What errors are handled? Retry logic? Failure modes?
```

## Workflow

### Phase 1: Codebase Exploration

**Determine documentation type first:**

- **Creating brand new documentation?** → Follow complete workflow below
- **Updating existing documentation?** → Read existing docs first, update changed sections only, validate updates

**For new documentation:**

1. **Understand project structure:**
   - Read package.json, requirements.txt, go.mod, Cargo.toml (dependency files)
   - Identify main entry points (main.py, index.js, main.go, etc.)
   - Map out directory structure

2. **Identify components:**
   - Find services, modules, packages
   - Identify databases, message queues, external APIs
   - Map dependencies between components

3. **Analyze data flow:**
   - Trace request lifecycle from entry to response
   - Document transformations at each stage
   - Capture exact payload examples when possible

### Phase 2: Documentation Generation

1. **Abstract:**
   - Write formal research paper abstract
   - Delineate system purpose, architectural approach, key technologies
   - Example: "This document delineates the architectural design of [System Name], a cloud-native platform engineered to [purpose]. Leveraging [technologies], the system [key approach] to deliver [outcomes]. The architecture adheres to the C4 model, decomposing abstractions from high-level system context to granular component implementation."

2. **Business Context:**
   - Extract from README, comments, or infer from code
   - Identify stakeholders (who uses this?)

3. **System Context Diagram:**
   - Create diagram using PlantUML/Kroki (see kroki-syntax.md), Mermaid (see mermaid-syntax.md), or Eraser (see eraser-syntax.md)
   - Show: system as a box, external actors (users, services, databases), connections

4. **High-Level Architecture:**
   - Create C4 Container diagram showing major components
   - Document data flow with concrete example ("hero scenario")
   - Show transformations: Input → Output at each stage

5. **Component Deep Dives:**
   - **Create Component Responsibility Matrix first:**
     - Table with columns: Component | Primary Responsibility | Key Dependencies | Input/Output | Failure Modes | Recovery Strategies
     - One row per major component
     - Provides quick reference for all components before detailed sections
   - For each major component:
     - Purpose (one sentence)
     - Implementation details (stack, algorithms, dependencies)
     - Engineering analysis (WHY this way, trade-offs, configuration rationale)
     - Create component-level diagram if complex

6. **Cross-Cutting Concerns:**
   - Document observability approach
   - Identify failure modes from code (error handling, retries)
   - Extract deployment configuration

7. **Decision Log:**
   - Document WHY decisions were made
   - Include context and consequences

7. **Optional Appendices (if applicable):**
   - **Technology Stack Summary:** Extract all technologies from dependency files and component details; organize by category
   - **API Endpoint Reference:** Document public/internal APIs with request/response schemas from code

### Phase 3: Diagram Generation

Three diagram engines are available. Choose based on needs:

**Option A: PlantUML via Kroki (default)** — Free, self-hostable, 25+ diagram engines, 900+ AWS cloud icons in stdlib.

**Option B: Mermaid** — GitHub/GitLab native rendering, dedicated `architecture-beta` diagram type, C4 support, Iconify icon ecosystem.

**Option C: Eraser** — Concise syntax, visual styling (watercolor, bold), requires API key.

#### PlantUML/Kroki Diagrams

Generate PlantUML code using cloud icon macros (see kroki-syntax.md and icon-reference.md):

````
```plantuml
@startuml System Context
!include <awslib/AWSCommon>
!include <awslib/General/Users>
!include <awslib/