# georgepearse/tsrs architecture

> Architecture diagram of the GitHub repository georgepearse/tsrs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/georgepearse/tsrs
- Repository: https://github.com/georgepearse/tsrs

## Overview

##### Project Type and Purpose
- This is a Rust-based command-line tool (tsrs-cli) for performing tree-shaking (dead-code elimination) on Python modules/packages and producing “slim” virtual environments or minified source files.
- It also exposes its core engine as a Python extension via PyO3 for direct library use.

##### File Structure Analysis
- src/bin/cli.rs & tsrs-minify-tree.rs: Two CLI entry points (main app and a specialized minify tool).
- src/lib.rs + modules (venv.rs, imports.rs, callgraph.rs, slim.rs, minify.rs, reporting.rs, error.rs): Core library implementing:
– Virtual environment discovery & analysis (venv),
– Python import extraction (imports),
– Call‐graph construction & dead code detection (callgraph),
– Slim‐venv creation (slim),
– Minified source rewriting (minify),
– Reporting & stats (reporting).
- scripts/: Utility scripts for build/bootstrap.
- docs/ + site/: MkDocs documentation.
- test_packages/ & tests/: Integration and unit test suites.
- Cargo.toml & mkdocs.yml: Build and doc configuration.

##### Key Architecture Descriptions from README
- Core engine stages:
1. Scan Python code for imports
2. Discover packages in a venv
3. Build call graph across modules
4. Detect dead/unused code
5. Produce slim venv or rewrite source files
- Modules are highly decoupled, communicating via well-defined data structures (AST extracts, call-graph models, plan JSON).

a. Main Components
- CLI Layer (tsrs-cli binary)
- Core Engine Library
- Venv Discovery Module
- Import Extraction Module
- Call-Graph Module
- Dead-Code Analysis Module
- Slim-Venv Creator
- Minify/Rewriter
- Reporting
- Python Extension (PyO3 wrapper)
- File System / Python Virtual Env (external)
- Tests & CI (Cargo test & GitHub Actions)
b. Relationships & Data Flow
- User invokes CLI → CLI parses flags (analyze/slim/minify/plan)
→ passes config to Core Engine
→ Venv module scans FS for installed packages
→ Imports module parses Python source into import lists
→ Call-Graph module builds usage graph
→ Dead-Code module marks unused nodes
→ Slim module copies only used packages to new venv
or Minify module rewrites source files in place or out-dir
→ Reporting module aggregates stats/JSON/diffs → CLI outputs results
- Python Extension provides library entry points calling the same Core Engine API.
c. Architectural Patterns / Principles
- Pipeline pattern: clear sequential stages (scan → analyze → transform → report).
- Modular design: each concern in its own module.
- High-precision, conservative dead-code elimination.
- Parallel processing (Rayon thread pool) for directory operations.
d. Key Technologies & Frameworks
- Rust/Cargo, Clap (CLI parsing), Rayon (parallel jobs), PyO3 (Python bindings), MkDocs (documentation), GitHub Actions (CI), Virtualenv & file system interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Extension Layer
    subgraph "Frontend Interfaces"
        direction TB
        CLI["tsrs-cli (CLI)"]:::frontend
        MinifyCLI["tsrs-minify-tree (CLI)"]:::frontend
        PyExt["PyO3 Python Extension"]:::frontend
    end

    %% Core Engine Modules
    subgraph "Core Engine" 
        direction TB
        Venv["Venv Discovery Module"]:::core
        Imports["Import Extraction Module"]:::core
        CallGraph["Call-Graph & Dead-Code Module"]:::core
        Slim["Slim-Venv Creator Module"]:::core
        Minify["Minified Source Rewriter Module"]:::core
        Reporting["Reporting & Statistics Module"]:::reporting
        Error["Error Handling & Common Types"]:::core
    end

    %% External Systems
    FS["Python Virtual Env (FS)"]:::external

    %% Outputs
    subgraph "Outputs"
        direction TB
        SlimOut["Slim Venv Output"]:::output
        Rewritten["Rewritten Source Files"]:::output
        ReportOut["Report & Stats JSON"]:::output
    end

    %% QA & CI
    subgraph "QA & CI"
        direction TB
        CI["CI Workflow"]:::external
        TestRust["Rust Integration & Unit Tests"]:::external
        TestPy["Python Test Packages"]:::external
    end

    %% Data Flow
    CLI -->|"config & flags"| Venv
    MinifyCLI -->|"config & flags"| Venv
    PyExt -->|"Library API Call"| Venv

    FS -->|"scan FS"| Venv
    Venv -->|"package list"| Imports
    Imports -->|"AST imports list"| CallGraph
    CallGraph -->|"call graph model"| Slim
    CallGraph -->|"call graph model"| Minify
    Slim -->|"used packages"| SlimOut
    Minify -->|"rewritten files"| Rewritten

    Slim --> Reporting
    Minify --> Reporting
    Reporting -->|"JSON/diffs"| ReportOut
    Reporting --> CLI
    Reporting --> MinifyCLI

    %% Error Handling references
    Venv --- Error
    Imports --- Error
    CallGraph --- Error
    Slim --- Error
    Minify --- Error
    Reporting --- Error

    %% QA & CI Flow
    CI --> TestRust
    CI --> TestPy
    TestRust --> CLI
    TestPy --> PyExt

    %% Click Events
    click CLI "https://github.com/georgepearse/tsrs/blob/master/src/bin/cli.rs"
    click MinifyCLI "https://github.com/georgepearse/tsrs/blob/master/src/bin/tsrs-minify-tree.rs"
    click PyExt "https://github.com/georgepearse/tsrs/blob/master/src/lib.rs"
    click Venv "https://github.com/georgepearse/tsrs/blob/master/src/venv.rs"
    click Imports "https://github.com/georgepearse/tsrs/blob/master/src/imports.rs"
    click CallGraph "https://github.com/georgepearse/tsrs/blob/master/src/callgraph.rs"
    click Slim "https://github.com/georgepearse/tsrs/blob/master/src/slim.rs"
    click Minify "https://github.com/georgepearse/tsrs/blob/master/src/minify.rs"
    click Reporting "https://github.com/georgepearse/tsrs/blob/master/src/reporting.rs"
    click Error "https://github.com/georgepearse/tsrs/blob/master/src/error.rs"
    click TestRust "https://github.com/georgepearse/tsrs/tree/master/tests/"
    click TestPy "https://github.com/georgepearse/tsrs/tree/master/test_packages/"
    click CI "https://github.com/georgepearse/tsrs/blob/master/.github/workflows/static.yml"
    click FS "https://github.com/georgepearse/tsrs/tree/master/n/a"
    click ReportOut "https://github.com/georgepearse/tsrs/blob/master/mkdocs.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#4A90E2,stroke-width:1px
    classDef core fill:#E8F6E8,stroke:#3C763D,stroke-width:1px
    classDef external fill:#F2F2F2,stroke:#999999,stroke-width:1px,stroke-dasharray: 5 5
    classDef reporting fill:#FFE8CC,stroke:#E67E22,stroke-width:1px
    classDef output fill:#FFF5E6,stroke:#D35400,stroke-width:1px,stroke-dasharray: 2 2
```
