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