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

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

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 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 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 } Component Diagram graph LR A [Component A] --> B [Component B] A --> C [Component C] B --> D [Component D] C --> D 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

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" 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.