# stochastic-sisyphus/code-cartographer architecture

> Architecture diagram of the GitHub repository stochastic-sisyphus/code-cartographer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stochastic-sisyphus/code-cartographer
- Repository: https://github.com/stochastic-sisyphus/code-cartographer

## Overview

##### Project type and purpose
- Code Cartographer is a Python-based, CLI-driven static analysis tool for Python codebases.
- It provides deep multilayer analysis (complexity, variants, hashes), generates reports (Markdown, Graphviz), and offers an interactive dashboard via HTML templates.

##### File structure
- Top level:
- `.github/workflows/publish.yml` (CI/CD for PyPI)
- `pyproject.toml`, `requirements.txt`, `setup` files (packaging & dependencies)
- `code_cartographer/cli.py` (entry point), `core/` (analysis engine), `templates/` (dashboard UI)
- `guide.md`, `README.md`, `LICENSE` (documentation)
- `tests/` (unit tests for analyzers)
- Key directories:
- `code_cartographer/core/` holds the Analyzer classes (`analyzer.py`, `variant_analyzer.py`)
- `templates/` has Jinja2 HTML templates for the interactive dashboard
- CLI serves as orchestrator and exposes commands

##### README for additional insights
- Core components: ProjectAnalyzer, VariantAnalyzer
- Outputs: Markdown summary (`analysis.md`, `variants.md`), Graphviz dependency graph (`*.dot`), interactive HTML dashboard
- External tools: Radon (complexity), Graphviz, Jinja2, LLM prompts

a. Main components
1. CLI Layer (code-cartographer commands)
2. Core Analysis Engine
- ProjectAnalyzer
- VariantAnalyzer
- Normalization & hashing module
- Complexity & maintainability metrics (Radon integration)
3. Data Model & Storage
- AST & metadata objects (classes/functions, docstrings, complexity scores)
- Variant groupings, semantic similarity results
4. Output Generators
- Markdown report generator
- Graphviz `.dot` generator (dependency graph)
- Jinja2 HTML dashboard renderer
5. Template Layer (`templates/dashboard.html.j2`)
6. External Services
- Radon library
- Graphviz binary (for rendering `.dot` files)
- Optionally an LLM API for refactor prompt generation

b. Relationships & interactions
- CLI Layer → invokes → Core Analysis Engine
- Core Engine → produces → intermediate Data Model
- Data Model → fed into → Output Generators
- Output Generators → write → files (Markdown, `.dot`, HTML)
- Template Layer ← used by ← HTML generator
- Core Engine ↔ calls → Radon & Semantic Analysis libraries
- `.dot` files → rendered by → Graphviz

c. Architectural patterns & principles
- Layered architecture: separation of CLI, processing engine, output layer
- Single responsibility: analyzers focus on code metrics, variant analyzers focus on semantic merging
- Extensibility: template-driven dashboard, plugin-like CLI flags for thresholds & exclusions
- Data flow is uni-directional (analysis → model → report)

d. Relevant technologies & libraries
- Python 3.8+
- Click or argparse (in `cli.py`) for command-line interface
- Radon for complexity & maintainability
- Jinja2 for HTML templating
- Graphviz for dependency visualization
- LLM prompt generation (internal module, optional API)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    CLI["CLI Layer"]:::cli
    click CLI "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/code_cartographer/cli.py"

    %% Core Analysis Engine
    subgraph "Core Analysis Engine"
        PA["ProjectAnalyzer"]:::core
        click PA "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/code_cartographer/core/analyzer.py"
        VA["VariantAnalyzer"]:::core
        click VA "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/code_cartographer/core/variant_analyzer.py"
        NH["Normalization & Hashing"]:::core
        CM["Complexity & Maintainability Metrics\n(CC>10, MI<65)"]:::core
    end

    %% Data Model
    DM["AST & Metadata Objects"]:::data

    %% Output Generators
    subgraph "Output Generators"
        MDG["Markdown Report Generator"]:::output
        click MDG "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/code_cartographer/cli.py"
        DGG["Graphviz .dot Generator"]:::output
        click DGG "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/code_cartographer/cli.py"
        HDR["HTML Dashboard Renderer"]:::output
        click HDR "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/code_cartographer/cli.py"
    end

    %% Template Layer
    TL["Dashboard Template\n(templates/dashboard.html.j2)"]:::template
    click TL "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/templates/dashboard.html.j2"

    %% Data Artifacts
    MD["analysis.md & variants.md"]:::artifact
    DOT["dependency_graph.dot"]:::artifact
    HTML["dashboard.html"]:::artifact

    %% External Services
    RAD["Radon Library"]:::external
    GZ["Graphviz Binary"]:::external
    LLM["LLM API (optional)"]:::external

    %% Project Management
    CI["CI/CD Pipeline"]:::external
    click CI "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/.github/workflows/publish.yml"
    PKG["Packaging & Dependencies\n(pyproject.toml, requirements.txt)"]:::external
    click PKG "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/pyproject.toml"
    click PKG "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/requirements.txt"
    DOC["Project Documentation\n(README.md, guide.md)"]:::external
    click DOC "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/README.md"
    click DOC "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/guide.md"
    UT["Unit Tests"]:::external
    click UT "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/tests/test_analyzer.py"
    click UT "https://github.com/stochastic-sisyphus/code-cartographer/blob/main/tests/test_variant_analyzer.py"

    %% Relationships
    CLI -->|"invoke"| PA
    CLI -->|"invoke"| VA
    PA -->|uses| NH
    PA -->|uses| CM
    PA -->|calls| RAD
    VA -->|semantic analysis| LLM
    PA -->|produce| DM
    VA -->|produce| DM
    DM -->|feed| MDG
    DM -->|feed| DGG
    DM -->|feed| HDR
    MDG -->|write| MD
    DGG -->|write| DOT
    DGG -->|render| GZ
    HDR -->|render with| TL
    HDR -->|write| HTML

    %% Side dependencies
    CLI --- PKG
    CLI --- CI
    CLI --- DOC
    PA --- UT
    VA --- UT

    classDef cli fill:#FDE047,stroke:#333,stroke-width:1px;
    classDef core fill:#BFDBFE,stroke:#1E3A8A,stroke-width:1px;
    classDef data fill:#E9D5FF,stroke:#6B21A8,stroke-width:1px;
    classDef output fill:#BBF7D0,stroke:#065F46,stroke-width:1px;
    classDef template fill:#FEF3C7,stroke:#92400E,stroke-width:1px;
    classDef artifact fill:#FECACA,stroke:#991B1B,stroke-width:1px;
    classDef external fill:#FDE68A,stroke:#92400E,stroke-width:1px;
```
