athola/class-diagram

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