/class-diagram

name: class-diagram
description: Generates a Mermaid class diagram showing types, inheritance, and composition. Use when visualizing class hierarchies or documenting a module public API.

Class Diagram

Generate a Mermaid class diagram showing types, their relationships, and public interfaces from a codebase.

When To Use

• Understanding class hierarchies and inheritance
• Documenting public APIs of a module
• Analyzing composition vs. inheritance patterns
• Answering "what types exist and how do they relate?"

When NOT To Use

• Module-level imports (use `cartograph:dependency-graph`)
• Runtime data movement (use `cartograph:data-flow`)

Workflow

Step 1: Explore the Codebase

Dispatch the codebase explorer agent:

Agent(cartograph:codebase-explorer)
Prompt: Explore [scope] and return a structural model.
Focus on classes, dataclasses, protocols, type aliases,
inheritance, and composition for a class diagram.
Extract: class names, methods (public only), attributes,
parent classes, and composed types.

Step 2: Generate Mermaid Syntax

Transform the structural model into a Mermaid class diagram.

**Rules for class diagrams**:

• Use `classDiagram` diagram type
• Show only public methods and key attributes
• Use Mermaid relationship notation:
• `<|--` for inheritance
• `*--` for composition
• `o--` for aggregation
• `..>` for dependency/usage
• Add stereotypes for special types:
• `<<protocol>>` for Python protocols/interfaces
• `<<dataclass>>` for dataclasses
• `<<enum>>` for enums
• `<<abstract>>` for abstract classes
• Limit to 12-15 classes maximum
• Group related classes with `namespace`
• Omit private methods and dunder methods
• Show return types for methods

**Example output**:

classDiagram
    class ResumeSession {
        +Path config_path
        +dict data
        +load() ResumeSession
        +to_pdf(Path) Path
        +to_html(Path) Path
    }

    class ResumeError {
        <<abstract>>
        +str message
        +str context
    }

    class ValidationError {
        +list~str~ fields
    }

    class RenderError {
        +str template
    }

    ResumeError <|-- ValidationError
    ResumeError <|-- RenderError
    ResumeSession ..> ResumeError

Step 3: Render via MCP

Call the Mermaid Chart MCP to render:

mcp__claude_ai_Mermaid_Chart__validate_and_render_mermaid_diagram
  prompt: "Class diagram of [scope]"
  mermaidCode: [generated syntax]
  diagramType: "classDiagram"
  clientName: "claude-code"

If rendering fails, fix syntax and retry (max 2 retries).

Step 4: Present Results

Show the rendered diagram with analysis notes:

• Total classes and relationship count
• Key inheritance hierarchies identified
• Composition patterns noted

Exit Criteria

• [ ] Mermaid `classDiagram` syntax generated with at least one class

definition including public methods or attributes

• [ ] `mcp__claude_ai_Mermaid_Chart__validate_and_render_mermaid_diagram`

called with `diagramType: "classDiagram"` and returns without error

• [ ] Analysis notes include total class count, identified inheritance

hierarchies, and composition patterns

• [ ] Private methods and dunder methods (`__init__`, `__repr__`, etc.)

are absent from the generated diagram

• [ ] Diagram contains at most 15 classes; if more exist in scope,

aggregation is applied and noted