References (archive): SCAFFOLD_SKILLS_ARCHIVE_MAP.md — Mermaid/output patterns from claude-flow code-intelligence, everything-claude-code architect.

Processing Limits (Memory Safeguard)

Diagram generator can analyze large codebases. To prevent memory exhaustion:

• File chunk limit: 1000 files per diagram (HARD LIMIT)

• Each file: ~1-5 KB analysis overhead

• 1000 files × 2 KB = ~2 MB per diagram

• Keeps diagram generation memory-efficient

Why the limit?

• Analyzing 5000+ files → 10+ MB memory → context explosion

• Diagrams for 5000+ files → impossible to visualize

• Visual limit: ~100-200 nodes per diagram (human readable)

Recommend:

• 1000 files: OK, generates ~100-150 component nodes

• 2000 files: Consider splitting into 2 diagrams

• 5000+ files: MUST split into 5+ diagrams by module/subsystem

Step 1: Identify Diagram Type

Determine what type of diagram is needed:

• Architecture Diagram: System structure and components

• Database Diagram: Schema and relationships

• Component Diagram: Component interactions

• Sequence Diagram: Process flows

• Flowchart: Decision flows

Step 2: Extract Structure

Analyze code and documentation (Use Parallel Read/Grep/Glob):

• Read architecture documents

• Analyze component structure

• Extract database schema

• Identify relationships

• Understand data flows

Chunking Large Codebases

If codebase has >1000 files:

Option 1: Split by subsystem

// Generate diagram for each major subsystem generateDiagram({ files: 'src/auth/', title: 'Authentication Module' }); generateDiagram({ files: 'src/api/', title: 'API Module' }); generateDiagram({ files: 'src/ui/**', title: 'UI Module' });

Option 2: Split by layer

generateDiagram({ files: 'src/models/', title: 'Data Models' }); generateDiagram({ files: 'src/services/', title: 'Business Logic' }); generateDiagram({ files: 'src/controllers/**', title: 'API Controllers' });

Option 3: Generate overview first, then details

// 1. High-level architecture (10-20 files) generateDiagram({ files: ["src/index.ts", "src/app.ts", ...], title: "Architecture" }); // 2. Detailed subsystems (500-1000 files each) generateDiagram({ files: "src/auth/**", title: "Authentication Details" });

Step 3: Generate Mermaid Diagram

Create diagram using Mermaid syntax:

• Use appropriate diagram type

• Define nodes and relationships

• Add labels and descriptions

• Include styling if needed

Step 4: Embed in Documentation

Embed diagram in markdown:

• Use mermaid code blocks

• Add diagram description

• Reference in documentation

Timeout Management

• Default timeout: 30 seconds per diagram

• 1000 files analysis: ~20 seconds (OK)

• 2000 files analysis: ~40 seconds (EXCEEDS TIMEOUT)

• If approaching timeout: Reduce file count or increase timeout

Pattern for large codebases:

• Split into 6-8 focused diagrams

• Each <1000 files, <30 seconds

• Total analysis time: 3-4 minutes

</execution_process>

Integration with Database Architect Agent:

• Generates database schema diagrams

• Documents table relationships

• Visualizes data models

Integration with Technical Writer Agent:

• Embeds diagrams in documentation

• Creates visual documentation

• Enhances documentation clarity

<best_practices>

• Use Mermaid: Standard syntax for compatibility

• Keep Clear: Simple, readable diagrams

• Show Relationships: Include all important connections

• Add Labels: Clear node and edge labels

• Update Regularly: Keep diagrams current with code </best_practices>

graph TB Client[Client Application] API[API Gateway] Auth[Auth Service] User[User Service] DB[(Database)]

Client --> API
API --> Auth
API --> User
User --> DB
Auth --> DB

</code_example>

<code_example> Database Schema Diagram

erDiagram USERS ||--o{ ORDERS : places USERS { uuid id PK string email string name } ORDERS ||--|{ ORDER_ITEMS : contains ORDERS { uuid id PK uuid user_id FK date created_at } ORDER_ITEMS { uuid id PK uuid order_id FK uuid product_id FK int quantity }

</code_example>

<code_example> Component Diagram

graph LR A[Component A] --> B[Component B] A --> C[Component C] B --> D[Component D] C --> D

</code_example>

<code_example> Sequence Diagram

sequenceDiagram participant User participant API participant Auth participant DB

User->>API: Login Request
API->>Auth: Validate Credentials
Auth->>DB: Query User
DB-->>Auth: User Data
Auth-->>API: JWT Token
API-->>User: Auth Response

</code_example>

Generate architecture diagram

node .claude/tools/diagram-generator/scripts/generate.mjs --type architecture "authentication system"

Generate database schema diagram

node .claude/tools/diagram-generator/scripts/generate.mjs --type database "user management module"

Generate component diagram

node .claude/tools/diagram-generator/scripts/generate.mjs --type component "API service relationships"

Generate sequence diagram

node .claude/tools/diagram-generator/scripts/generate.mjs --type sequence "user login flow"

</usage_example>

Iron Laws

• ALWAYS use Mermaid syntax for all generated diagrams — never produce free-form ASCII art or PlantUML; only Mermaid is portable and version-controllable.

• NEVER exceed 200 nodes in a single diagram — beyond that threshold the diagram becomes cognitively unreadable; split large systems into multiple focused diagrams by subsystem.

• ALWAYS enforce the 1000-file hard limit per diagram generation run — analyzing more files without chunking causes context explosion and memory exhaustion.

• NEVER write diagram files to project root or arbitrary locations — all diagrams go to .claude/context/artifacts/diagrams/ with the naming convention {subject}-{type}-{YYYY-MM-DD}.mmd .

• ALWAYS label connections that are not self-evidently directional — an unlabeled arrow between two ambiguously-named nodes is indistinguishable from any other relationship.

Anti-Patterns

Anti-Pattern Why It Fails Correct Approach

Generating a single diagram for 500+ node systems Unreadable; cognitive overload; renders as noise Split by subsystem: overview diagram (10-20 nodes) + detail diagrams per module

Using free-form ASCII art instead of Mermaid Not renderable in standard tools; not version-diffable Use Mermaid syntax exclusively; all tools that render code docs support it

Analyzing all files without chunking

1000 files causes context explosion and timeouts Enforce 1000-file hard limit; spawn multiple diagram tasks for large codebases

Writing diagrams to arbitrary paths Diagrams become unfindable; no catalog integration Always write to .claude/context/artifacts/diagrams/{subdir}/

Defaulting to graph TB for every diagram type Wrong layout for sequence/ER/class content; forces readers to mentally remap Use the Diagram Type Selection Matrix to pick the correct type for the content

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md

• Issue found -> .claude/context/memory/issues.md

• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.