Architecture Docs

Skill: Create Architecture Documentation

Trigger

When the user needs to document system architecture or make Architecture Decision Records (ADRs).

Prerequisites

• [ ] Codebase or design available to analyze
• [ ] docs/ or docs/architecture/ directory exists (or create it)
• [ ] Mermaid support in docs (GitHub, MkDocs, etc.)

Steps

Step 1: System Overview

• [ ] High-level architecture diagram (Mermaid)
• [ ] List all services/components
• [ ] Document communication patterns
• [ ] Document data flow

Step 2: Component Documentation

For each service/component:

• [ ] Purpose and responsibilities
• [ ] Technology stack
• [ ] API contracts (if applicable)
• [ ] Data stores
• [ ] Dependencies
• [ ] Scaling characteristics

Step 3: Architecture Decision Records (ADRs)

For significant decisions:

• [ ] Title: Short descriptive title
• [ ] Status: Proposed / Accepted / Deprecated / Superseded
• [ ] Context: Why this decision is needed
• [ ] Decision: What was decided
• [ ] Consequences: Trade-offs and implications

ADR template:

# ADR-{number}: {title}

## Status
{Proposed | Accepted | Deprecated | Superseded by ADR-{n}}

## Context
{What is the issue that we're seeing that is motivating this decision?}

## Decision
{What is the change that we're proposing and/or doing?}

## Consequences
{What becomes easier or harder because of this change?}

Step 4: Data Flow Diagrams

• [ ] Request flow through the system
• [ ] Event/message flow
• [ ] Data pipeline flow
• [ ] Authentication flow

Step 5: Operational Documentation

• [ ] Deployment architecture
• [ ] Monitoring and alerting overview
• [ ] Disaster recovery plan
• [ ] Scaling procedures

Completion Checklist

• [ ] At least one diagram (Mermaid) for system or data flow
• [ ] ADRs for significant decisions (format, status, context, decision, consequences)
• [ ] Component list with purpose and tech stack
• [ ] Operational section (deploy, monitor, scale)

If Step Fails

• Step 1 (overview): Start with 3–5 boxes; add detail later. Use flowchart LR or flowchart TB for simple flows
• Step 3 (ADRs): Number format ADR-001; keep each ADR to one decision
• Step 4 (diagrams): Mermaid syntax: no spaces in node IDs; use A[Label] not A[Label with spaces]

Example

Step 1: flowchart LR with Client -> API -> DB, API -> Cache. Step 3: ADR-001 Use PostgreSQL — Status Accepted, Context: need relational, Decision: PostgreSQL, Consequences: SQL expertise required.