Explain Code

Code Visualizer with Excalidraw

Explain source code through structured text explanations and hand-drawn style Excalidraw diagrams.

About Excalidraw

• Open source at excalidraw.com and GitHub
• Hand-drawn/sketchy aesthetic
• Real-time collaboration support
• Browser-based, no sign-up required
• .excalidraw JSON format
• Embeddable via @excalidraw/excalidraw npm package

Workflow

1. Receive code input with optional context
2. Analyze code structure, patterns, and flow
3. Select appropriate diagram type(s)
4. Generate text explanation with key insights
5. Create .excalidraw JSON diagram
6. Output to user's working directory or specified location

Input Handling

Accept code in these formats:

<code language="python">
def example():
    pass
</code>

Or with context:

<code language="typescript" context="Authentication module for REST API">
...
</code>

Or request type:

<request type="class_diagram">
Visualize the User authentication system
</request>

Code Analysis

Parse and Identify

Identify Patterns

• Control flow (conditionals, loops, error handling)
• Data flow (input → processing → output)
• Design patterns (singleton, factory, observer, etc.)
• Architecture patterns (MVC, layered, microservices)

Diagram Selection

Multiple diagrams may be appropriate for complex code.

Explanation Structure

Every code explanation includes:

1. High-Level Overview

Brief summary of what the code does and its purpose.

2. Key Components

List main classes, functions, or modules with roles.

3. Step-by-Step Logic

Walk through the execution flow with numbered steps.

4. Data Flow

Describe how data moves through the system.

5. Design Decisions

Note patterns used and architectural choices.

6. Performance Notes (if relevant)

Complexity, bottlenecks, optimization opportunities.

7. Potential Improvements (if relevant)

Suggestions for refactoring or enhancement.

Excalidraw JSON Structure

{
  "type": "excalidraw",
  "version": 2,
  "source": "code-visualizer",
  "elements": [...],
  "appState": {
    "gridSize": 20,
    "viewBackgroundColor": "#ffffff"
  },
  "files": {}
}

Element Reference

CRITICAL: Every element MUST include these base properties for proper rendering:

{
  "version": 1, "versionNonce": 1, "isDeleted": false,
  "seed": <unique_number>, "angle": 0, "opacity": 100,
  "groupIds": [], "frameId": null, "boundElements": [],
  "updated": 1, "link": null, "locked": false
}

Text elements also need: containerId, originalText, lineHeight, verticalAlign Lines/arrows also need: lastCommittedPoint, startBinding, endBinding, startArrowhead, endArrowhead

See references/diagram-templates.md for complete examples.

Shapes

Rectangle (classes, entities, processes) - key properties:

{
    "type": "rectangle",
    "id": "rect_1",
    "x": 100,
    "y": 100,
    "width": 200,
    "height": 120,
    "strokeColor": "#1e1e1e",
    "backgroundColor": "#a5d8ff",
    "fillStyle": "solid",
    "strokeWidth": 2,
    "roughness": 1,
    "roundness": { "type": 3 }
}

Diamond (decisions) - key properties:

{
    "type": "diamond",
    "id": "diamond_1",
    "x": 150,
    "y": 200,
    "width": 100,
    "height": 80,
    "backgroundColor": "#ffec99"
}

Ellipse (start/end, actors) - key properties:

{
    "type": "ellipse",
    "id": "ellipse_1",
    "x": 100,
    "y": 100,
    "width": 80,
    "height": 80,
    "backgroundColor": "#b2f2bb"
}

Connectors

Arrow (relationships, flow) - key properties:

{
    "type": "arrow",
    "id": "arrow_1",
    "x": 300,
    "y": 160,
    "points": [
        [0, 0],
        [100, 0]
    ],
    "strokeWidth": 2,
    "endArrowhead": "arrow"
}

Line (connections, dividers) - key properties:

{
    "type": "line",
    "id": "line_1",
    "x": 100,
    "y": 145,
    "points": [
        [0, 0],
        [200, 0]
    ],
    "strokeWidth": 1
}

Text

Key properties (must also include text-specific required props):

{
    "type": "text",
    "id": "text_1",
    "x": 110,
    "y": 110,
    "text": "ClassName",
    "fontSize": 16,
    "fontFamily": 1,
    "textAlign": "center",
    "originalText": "ClassName",
    "lineHeight": 1.25,
    "verticalAlign": "top",
    "containerId": null
}

Color Palette

Relationship Arrows

Layout Guidelines

1. Grid: Align to 100px grid
2. Spacing: Minimum 50px between elements
3. Flow: Left-to-right or top-to-bottom
4. Grouping: Cluster related components
5. Hierarchy: Important elements at top/left
6. Labels: Center text, 10px padding from edges

ID Generation

Format: {type}_{index}_{random5}

import random, string
def gen_id(t, i):
    return f"{t}_{i}_{''.join(random.choices(string.ascii_lowercase+string.digits,k=5))}"

Output Format

For each visualization:

1. Text explanation in conversation
2. Diagram file saved to ./{name}.excalidraw or user-specified path
3. Usage instructions for opening/editing

Example naming: auth-system-class-diagram.excalidraw

Detailed Patterns

For specific diagram patterns, templates, and complete examples, see:

• references/diagram-templates.md - Element templates
• references/code-patterns.md - Code-to-diagram mapping