Architecture Documentation Skill

Overview

This skill provides patterns for creating clear, maintainable architecture documentation with properly formatted Mermaid diagrams.

When to Use

• Creating system architecture diagrams
• Documenting data flows
• Writing implementation plans
• Creating entity relationship diagrams
• Updating docs/implementation-plan/

---

Mermaid Diagram Best Practices

CRITICAL: Quote Special Characters

Mermaid will break on unquoted special characters. ALWAYS quote node labels containing:

| Character | Example | Wrong | Correct | |-----------|---------|-------|---------| | Parentheses | (info) | A[Label (info)] | A["Label (info)"] | | Brackets | [0] | A[Array [0]] | A["Array [0]"] | | Angle brackets | <table> | A[Id<table>] | A["Id<table>"] | | Colon | : | A[Key: Value] | A["Key: Value"] | | Ampersand | & | A[A & B] | A["A & B"] | | Greater/Less | >, < | A[x > 5] | A["x > 5"] | | Pipe | \| | A[A \| B] | A["A \| B"] | | Question mark | ? | A[Is valid?] | A["Is valid?"] |

Flowchart Template

flowchart TD
    subgraph Input["📥 Input Layer"]
        A["SAM.gov API"]
        B["eMMA Scraper"]
        C["RFPMart API"]
    end

    subgraph Processing["⚙️ Processing"]
        D["Canonical Schema"]
        E["Deduplication"]
        F{"Eligibility Gate"}
    end

    subgraph Output["📤 Output"]
        G["ELIGIBLE"]
        H["PARTNER_REQUIRED"]
        I["REJECTED"]
    end

    A --> D
    B --> D
    C --> D
    D --> E
    E --> F
    F -->|"Pass"| G
    F -->|"Partner needed"| H
    F -->|"Fail"| I

Sequence Diagram Template

sequenceDiagram
    participant U as "User"
    participant FE as "React Frontend"
    participant BE as "Convex Backend"
    participant AI as "Gemini AI"

    U->>FE: Click "Evaluate"
    FE->>BE: mutation("evaluations.run")
    BE->>BE: Check eligibility first
    alt Eligible
        BE->>AI: Send evaluation prompt
        AI-->>BE: Return JSON result
        BE-->>FE: Evaluation complete
    else Not Eligible
        BE-->>FE: Return rejection reason
    end
    FE-->>U: Show result

Entity Relationship Diagram Template

erDiagram
    OPPORTUNITY ||--o{ EVALUATION : "has"
    OPPORTUNITY ||--o| PURSUIT : "may have"
    EVALUATION ||--|| ELIGIBILITY : "contains"
    EVALUATION ||--o{ DIMENSION_SCORE : "contains"
    PURSUIT ||--o{ NOTE : "has"
    PURSUIT ||--o| BRIEF : "has"
    USER ||--o{ PURSUIT : "owns"

    OPPORTUNITY {
        string id PK
        string title
        string source
        number dueDate
    }

    EVALUATION {
        string id PK
        string opportunityId FK
        string eligibilityStatus
        number totalScore
    }

State Diagram Template

stateDiagram-v2
    [*] --> New
    New --> Triage: Review
    Triage --> Bid: Decide to pursue
    Triage --> NoBid: Decide to skip
    Bid --> Capture: Start capture
    Capture --> Draft: Begin writing
    Draft --> Review: Submit for review
    Review --> Draft: Request changes
    Review --> Submitted: Approve
    Submitted --> Won: Award received
    Submitted --> Lost: Not selected
    NoBid --> [*]
    Won --> [*]
    Lost --> [*]

---

Documentation Structure

Implementation Plan Structure

docs/implementation-plan/
├── README.md                    # Executive summary
│   - High-level architecture diagram
│   - Phase timeline table
│   - Success metrics
│   - Approval checklist
│
├── phase-N-[name]/README.md     # Phase details
│   - Objectives
│   - Data model changes
│   - Code examples
│   - Implementation checklist
│   - Files to create/modify
│
└── architecture/
    ├── README.md                # Multi-level architecture
    │   - Executive view (business flow)
    │   - Technical view (system components)
    │   - Implementation view (file structure)
    │
    └── DATABASE-SCHEMA.md       # Complete schema
        - Entity relationship diagram
        - Table definitions
        - Index definitions
        - Complete schema.ts code

Feature Documentation Structure

docs/features/[feature-name]/
├── README.md           # Problem, solution, success criteria
├── ARCHITECTURE.md     # Technical design with diagrams
└── IMPLEMENTATION.md   # Step-by-step plan with checklists

---

ASCII Diagrams

For inline documentation or simpler contexts, use ASCII art:

Box Diagram

┌─────────────────────────────────────────────────────────┐
│                    PROCESSING PIPELINE                   │
├─────────────────────────────────────────────────────────┤
│  INGEST → DEDUPE → ELIGIBILITY → SCORE → PIPELINE       │
└─────────────────────────────────────────────────────────┘

Flow Diagram

┌──────────┐    ┌──────────┐    ┌──────────┐
│  INPUT   │───▶│ PROCESS  │───▶│  OUTPUT  │
└──────────┘    └──────────┘    └──────────┘

Decision Tree

                    ┌─────────────┐
                    │   START     │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │  Eligible?  │
                    └──────┬──────┘
                     Yes   │   No
              ┌────────────┴────────────┐
              ▼                         ▼
       ┌──────────┐              ┌──────────┐
       │  SCORE   │              │  REJECT  │
       └──────────┘              └──────────┘

---

Quick Reference

Audience-Specific Diagrams

| Audience | Diagram Type | Focus | |----------|--------------|-------| | Executive | Flowchart | Business value flow | | Architect | Component diagram | System boundaries | | Developer | Sequence diagram | API interactions | | DBA | ERD | Data relationships |

Diagram Checklist

• [ ] All special characters are quoted
• [ ] Subgraph labels are descriptive
• [ ] Arrows have labels where helpful
• [ ] Colors/styles are consistent
• [ ] Diagram renders without errors