# y1ssh/micrograd1 architecture

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

- Interactive diagram: https://gitdiagram.com/y1ssh/micrograd1
- Repository: https://github.com/y1ssh/micrograd1

## Overview

##### Project type and purpose
- This is a Python library (“micrograd”) that provides:
- A tiny automatic differentiation engine (reverse-mode autodiff) operating on scalar values
- A minimal neural network module with a PyTorch-like API built on the autodiff engine
- Utility notebooks for demonstration and graph visualization
- It’s designed primarily for educational use to illustrate backpropagation and neural nets from first principles.

##### High-level component identification
- Core Engine (micrograd/engine.py):
- Class Value, computational graph construction, forward ops, backward (backprop)
- Neural Network API (micrograd/nn.py):
- Neuron, Layer, MLP classes that wrap and compose Value operations
- Visualization (trace_graph.ipynb & draw_dot):
- Graphviz integration to render the computational graph
- Demo Notebook (demo.ipynb):
- Example training loop, loss computation, parameter updates (SGD)
- Testing (test/test_engine.py):
- Unit tests comparing gradients against PyTorch as ground truth
- Packaging & Distribution:
- setup.py for PyPI, LICENSE, README.md, .gitignore

##### Relationships and data flow
- User code / notebooks → import micrograd.engine.Value → build computational graph
- User code / nn module → import micrograd.engine.Value to define neurons & layers
- Forward pass: Value ops produce new Value nodes, assembling a Directed Acyclic Graph (DAG)
- Backward pass: Value.backward() traverses the DAG in reverse, accumulating gradients
- draw_dot(y) inspects Value DAG nodes and emits Graphviz DOT for visualization
- Tests import Value, compute gradients, compare to PyTorch gradients

##### Architectural patterns & design principles
- Single-package modular design: engine.py is the “core” module; nn.py is a higher-level wrapper
- Dynamic computational graph pattern (like PyTorch’s eager mode)
- Separation of concerns:
- Core numerical engine vs. neural-network abstractions vs. visualization vs. tests
- Minimal external dependencies: only graphviz for visualization, pytest and PyTorch for tests

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core modules
    subgraph "Core Modules"
        Engine["micrograd.engine\n(Value, DAG, backprop)"]:::core
        NN["micrograd.nn\n(Neuron, Layer, MLP)"]:::core
    end

    %% Clients
    subgraph "Client Notebooks"
        Demo["Demo Notebook"]:::client
        Viz["Visualization Notebook"]:::client
    end

    Test["Test Suite"]:::client
    Pack["Packaging & Distribution\n(setup.py, LICENSE, README.md, .gitignore)"]:::pack

    %% External dependencies
    Graphviz["Graphviz"]:::external
    PyTorch["PyTorch"]:::external
    pytest["pytest"]:::external

    %% Relationships
    NN -->|imports/uses| Engine
    Demo -->|imports| Engine
    Demo -->|imports| NN
    Viz -->|uses draw_dot| Engine
    Viz -->|outputs| Graphviz
    Test -->|imports| Engine
    Test -->|compares grads with| PyTorch
    Test -->|runs on| pytest
    Pack -.->|publishes| Engine
    Pack -.->|publishes| NN

    %% Click Events
    click Engine "https://github.com/y1ssh/micrograd1/blob/master/micrograd/engine.py"
    click NN "https://github.com/y1ssh/micrograd1/blob/master/micrograd/nn.py"
    click Viz "https://github.com/y1ssh/micrograd1/blob/master/trace_graph.ipynb"
    click Demo "https://github.com/y1ssh/micrograd1/blob/master/demo.ipynb"
    click Test "https://github.com/y1ssh/micrograd1/blob/master/test/test_engine.py"
    click Pack "https://github.com/y1ssh/micrograd1/blob/master/setup.py"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#1B4F72,stroke-width:2px;
    classDef client fill:#D5F5E3,stroke:#196F3D,stroke-width:2px;
    classDef external fill:#FADBD8,stroke:#922B21,stroke-width:2px;
    classDef pack fill:#F2F4F4,stroke:#566573,stroke-width:2px;
```
