generating-docs

Generating Architecture Documentation

Overview

Systematic approach to analyzing a codebase and producing three visual documentation artifacts: architecture overview (Mermaid), data flow diagrams (Mermaid), and an interactive function call graph (HTML/Cytoscape.js).

When to Use

• User asks to document or visualize a codebase
• Starting work on an unfamiliar project and need orientation
• Codebase has changed significantly and docs are stale
• Onboarding someone to a project

Analysis Strategy

Step 1: Reconnaissance

Before generating anything, understand the project:

1. Read top-level files: package.json, pyproject.toml, Cargo.toml, go.mod, etc.
2. Map directory structure (2 levels deep)
3. Identify entry points: main files, app factories, route registrations
4. Identify the tech stack: framework, ORM, API style (REST/GraphQL/RPC)

Step 2: Architecture Analysis

Identify layers by reading actual source files:

Layer	What to look for
Entry/API	Route definitions, controllers, handlers, CLI commands
Business Logic	Service classes, use cases, domain models, validators
Data Access	ORM models, repositories, database queries, migrations
Infrastructure	Config loading, logging, caching, external API clients
Shared	Utilities, types, constants, middleware

For Python projects: look for urls.py, views.py, models.py, services/, api/ For TypeScript projects: look for routes/, controllers/, services/, models/, lib/

Step 3: Data Flow Tracing

Pick the 3-5 most important operations by looking at:

• Route handlers with the most logic
• Functions called from multiple places
• Data transformation pipelines
• Authentication/authorization flows

Trace each operation through the layers, noting:

• Entry point (which route/command/event)
• Each function call in sequence
• Data shape changes
• Side effects (DB writes, API calls, events emitted)

Step 4: Call Graph Extraction

For function call graphs, systematically:

1. List all modules/files in scope
2. For each file, extract function/method/class definitions
3. For each function, identify calls to other functions in the codebase (ignore stdlib/framework calls)
4. Record: {caller: "module.function", callee: "module.function"}

Group nodes by module. Identify:

• Entry points: functions with no callers within the codebase
• Hotspots: functions called by 3+ other functions
• Leaf nodes: functions that don't call other project functions

Output Formats

Architecture Overview (Mermaid)

Use graph TD for top-down layer diagrams:

graph TD
    subgraph API Layer
        routes[Routes/Controllers]
        middleware[Middleware]
    end
    subgraph Business Logic
        services[Services]
        validators[Validators]
    end
    subgraph Data Layer
        models[Models/ORM]
        repos[Repositories]
    end

    routes --> services
    middleware --> routes
    services --> validators
    services --> repos
    repos --> models

Data Flow (Mermaid Sequence Diagrams)

Use sequenceDiagram for each operation:

sequenceDiagram
    participant Client
    participant Router
    participant AuthService
    participant UserRepo
    participant DB

    Client->>Router: POST /login
    Router->>AuthService: authenticate(credentials)
    AuthService->>UserRepo: findByEmail(email)
    UserRepo->>DB: SELECT * FROM users
    DB-->>UserRepo: user record
    UserRepo-->>AuthService: User
    AuthService-->>Router: JWT token
    Router-->>Client: 200 {token}

Call Graph (JSON for Cytoscape.js)

Generate this JSON structure and embed in the HTML viewer template at ${CLAUDE_PLUGIN_ROOT}/skills/generating-docs/html-viewer.html:

{
  "nodes": [
    {"data": {"id": "module.func", "label": "func", "module": "module", "type": "entry|hotspot|normal|leaf"}}
  ],
  "edges": [
    {"data": {"source": "module.caller", "target": "module.callee"}}
  ],
  "modules": ["module1", "module2"]
}

Node types determine visual styling:

• entry: green border - no callers in codebase
• hotspot: red border, larger - called by 3+ functions
• normal: default styling
• leaf: gray, smaller - no outgoing calls

Common Mistakes

• Hallucinating structure: Always read actual files. Never guess what a module contains.
• Too granular: For call graphs, skip trivial utility functions (logging, formatting). Focus on business logic calls.
• Too abstract: Diagrams should use actual module/function names from the code, not generic placeholders.
• Missing error paths: In sequence diagrams, show at least one error/failure path per operation.
• Ignoring config: Check for dependency injection, config-driven routing, or dynamic imports that affect architecture.

Quick Reference

Artifact	Format	Key Content
Architecture	Mermaid graph TD	Layers, components, dependencies
Data Flow	Mermaid sequenceDiagram	Operations traced through layers
Call Graph	HTML + Cytoscape.js	Functions, calls, modules, hotspots