architecture-docs

Use this skill when creating, updating, or maintaining ARCHITECTURE.md files, when users ask about "my architecture documentation" or "architecture", when generating presentations/slides/PowerPoint from architecture documentation, when generating diagrams from architecture documentation, when validating/checking/auditing architecture (including BIAN alignment, META layers, standards compliance), or when answering questions about documented components, data structures, integrations, security, performance, deployment, technology stack, or architectural decisions

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

When & Why to Use This Skill

This Claude skill automates the creation and maintenance of professional technical architecture documentation. It specializes in generating precise Mermaid diagrams, structuring implementation plans, and ensuring system designs are well-documented, compliant with standards, and easily accessible within the development workflow. By bridging the gap between high-level design and implementation, it helps teams maintain a 'single source of truth' for their technical stack.

Use Cases

  • Automated generation of Mermaid flowcharts, sequence diagrams, and ERDs to visualize complex system interactions and data flows.
  • Creating and updating ARCHITECTURE.md and implementation plans to ensure documentation stays in sync with code changes.
  • Standardizing technical documentation across projects using structured templates for features, database schemas, and state transitions.
  • Auditing architectural designs for compliance with industry standards (like BIAN) and internal security or performance requirements.
  • Converting complex architectural decisions into readable documentation for diverse audiences, from executives to developers.
namearchitecture-docs
descriptionCreate and maintain architecture documentation with Mermaid diagrams. Use when writing technical documentation, system diagrams, or updating the implementation plan.
allowed-toolsRead, Write, Edit, Glob, Grep

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