# minitorch/module-0 architecture

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

- Interactive diagram: https://gitdiagram.com/minitorch/module-0
- Repository: https://github.com/minitorch/module-0

## Overview

##### Project type and purpose
- This is a small open-source Python library (“minitorch”) providing basic automatic differentiation, tensor operators, modules, and datasets, plus a set of example/demo applications under the `project/` directory.
- The core library lives in `minitorch/` and is accompanied by example front-ends (CLI and Streamlit) under `project/`.

##### File structure
- Top level: packaging/config (setup.py, pyproject.toml, requirements.txt), tests/, README.
- `minitorch/`: the core library, with submodules for operators, modules (neural-net style layers), datasets, and testing utilities.
- `project/`: example drivers and interfaces.
- `app.py` and `graph_builder.py` orchestrate demos.
- `interface/`: Streamlit-based UI components (`plots.py`, `streamlit_utils.py`, `train.py`).
- `math_interface.py` and `module_interface.py`: adapters exposing `minitorch` primitives to the front-ends.
- `run_manual.py` and `run_torch.py`: CLI scripts—`run_manual` uses pure `minitorch`, `run_torch` uses real PyTorch.
- `tests/`: unit tests for operators and modules.

##### Key insights from README
- This is Module 0 of “MiniTorch,” focusing on implementing the core autodiff and layer abstractions.
- It’s both a library and a learning/demo environment.

##### Main components
a. Core Library (“minitorch”)
- Operators (elementwise ops, matmul)
- Tensor and automatic-diff engine
- Module abstraction (parameters, forward/backward hooks)
- Datasets (toy data loaders)
- Testing utilities
b. Interfaces / Adapters
- math_interface.py (exposes scalar/tensor functions)
- module_interface.py (exposes Module classes to runners)
c. Example Applications
- CLI runners: `run_manual.py` (pure minitorch), `run_torch.py` (delegates to PyTorch)
- Streamlit UI: `interface/train.py` (training loop), `plots.py`, `streamlit_utils.py`, `app.py` (entry point)
- Graph builder: constructs and visualizes computational graph
d. External Dependencies
- PyTorch (only in `run_torch.py`)
- Streamlit (UI)
- Standard Python packages (numpy, etc.)
e. Tests
- Unit tests validate operators and modules

##### Relationships and data flows
- User → CLI runner or Streamlit UI
- Runner/UI → Interface layer (math_interface or module_interface)
- Interface → Core Library (invokes operators, builds graphs, runs forward/backward)
- Core Library ↔ Datasets (loads toy data)
- Core Library → Outputs gradients, metrics → Interface (for plotting or print)
- `run_torch.py` path: Interface → PyTorch library → returns results

##### Architectural patterns and principles
- Modular separation: core library vs. interface vs. demos
- Adapter pattern: math_interface & module_interface mediate between core and front-ends
- Single responsibility: each script or module has a focused role (operators only do ops, graph_builder only builds graphs, etc.)
- Test-driven: testing module ensures correctness of core primitives

##### Elements to include for clarity
- Arrowheads indicating data/control flow direction.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Layer 1: User & Scripts
    subgraph "Layer 1: User & Scripts"
        U[/"User"/]:::external
        RM["run_manual.py"]:::frontend
        RT["run_torch.py"]:::frontend
        APP["app.py"]:::frontend
        GB["graph_builder.py"]:::frontend
    end

    %% Layer 2: Adapter Interfaces
    subgraph "Layer 2: Adapter Interfaces"
        MI["math_interface.py"]:::adapter
        MOI["module_interface.py"]:::adapter
    end

    %% Layer 3: Core Library
    subgraph "Layer 3: Core Library"
        OPS["minitorch/operators.py"]:::library
        TA["minitorch/__init__.py"]:::library
        MA["minitorch/module.py"]:::library
        DS["minitorch/datasets.py"]:::library
        TU["minitorch/testing.py"]:::library
    end

    %% Layer 4: External Dependencies & Data
    subgraph "Layer 4: External Dependencies & Data"
        PT[("PyTorch")]:::external
        ST[("Streamlit")]:::external
        NP[("NumPy & Std Lib")]:::external
    end

    %% Layer 5: Tests
    subgraph "Layer 5: Tests"
        TO["tests/test_operators.py"]:::tests
        TM["tests/test_module.py"]:::tests
        TS["tests/strategies.py"]:::tests
    end

    %% Connections: User to Frontends
    U -->|uses CLI| RM
    U -->|uses CLI| RT
    U -->|opens UI| APP
    U -->|runs graph demo| GB

    %% Frontends to Adapters
    RM -->|"calls adapters"| MI
    RM -->|"calls adapters"| MOI
    RT -->|"calls adapters"| MI
    RT -->|"calls adapters"| MOI
    APP -->|"calls adapters"| MI
    APP -->|"calls adapters"| MOI
    GB -->|"calls adapters"| MI

    %% Adapters to Core
    MI -->|"invokes ops & engine"| OPS
    MI -->|"invokes ops & engine"| TA
    MOI -->|"invokes modules"| MA
    MI -->|"loads datasets"| DS
    MOI -->|"loads datasets"| DS

    %% Core to External Dependencies & Data
    RT -->|"delegates to"| PT
    APP -->|"renders UI"| ST
    OPS -->|"uses numeric"| NP
    TA -->|"uses numeric"| NP
    DS -->|"uses numeric"| NP

    %% Core interactions
    OPS -->|"register ops"| TA
    MA -->|"defines layers"| TA
    DS -->|"provides data"| TA
    TA -->|"triggers backward"| MA

    %% Core back to Frontends
    OPS -->|"forward/backward results"| MI
    TA -->|"gradients & metrics"| MOI
    MOI -->|"results"| RM
    MOI -->|"results"| APP
    MI -->|"results"| GB

    %% Tests to Core
    TO -->|"tests ops"| OPS
    TM -->|"tests modules"| MA
    TS -->|"strategies for tests"| TO
    TS -->|"strategies for tests"| TM

    %% Click Events
    click OPS "https://github.com/minitorch/module-0/blob/master/minitorch/operators.py"
    click TA "https://github.com/minitorch/module-0/blob/master/minitorch/__init__.py"
    click MA "https://github.com/minitorch/module-0/blob/master/minitorch/module.py"
    click DS "https://github.com/minitorch/module-0/blob/master/minitorch/datasets.py"
    click TU "https://github.com/minitorch/module-0/blob/master/minitorch/testing.py"
    click MI "https://github.com/minitorch/module-0/blob/master/project/math_interface.py"
    click MOI "https://github.com/minitorch/module-0/blob/master/project/module_interface.py"
    click RM "https://github.com/minitorch/module-0/blob/master/project/run_manual.py"
    click RT "https://github.com/minitorch/module-0/blob/master/project/run_torch.py"
    click APP "https://github.com/minitorch/module-0/blob/master/project/app.py"
    click GB "https://github.com/minitorch/module-0/blob/master/project/graph_builder.py"
    click APP "https://github.com/minitorch/module-0/blob/master/project/app.py"
    click TRAIN "https://github.com/minitorch/module-0/blob/master/project/interface/train.py"
    click PLOTS "https://github.com/minitorch/module-0/blob/master/project/interface/plots.py"
    click STREAMUTIL "https://github.com/minitorch/module-0/blob/master/project/interface/streamlit_utils.py"
    click TO "https://github.com/minitorch/module-0/blob/master/tests/test_operators.py"
    click TM "https://github.com/minitorch/module-0/blob/master/tests/test_module.py"
    click TS "https://github.com/minitorch/module-0/blob/master/tests/strategies.py"

    %% Class Definitions
    classDef library fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef adapter fill:#d4edda,stroke:#28a745,color:#000;
    classDef frontend fill:#ffe5b4,stroke:#ff9900,color:#000;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef tests fill:#f8d7da,stroke:#dc3545,color:#000;
```
