# jamormoussa/nanotorch architecture

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

- Interactive diagram: https://gitdiagram.com/jamormoussa/nanotorch
- Repository: https://github.com/jamormoussa/nanotorch

## Overview

##### Project type and purpose
- NanoTorch is an open-source, pure-Python deep learning micro-framework inspired by PyTorch.
- Its goal is educational: to illustrate how tensors, layers, losses, and optimizers interact under the hood using only NumPy.

##### File structure
- Top-level:
- main.py – a demonstration or CLI entry point.
- test.py & test/ – example and unit tests exercising the library.
- docs/ + mkdocs.yml – documentation site source for MkDocs, including notebooks and markdown.
- .github/workflows/deploy.yml – CI/CD pipeline for building and deploying the docs.
- Core package: nanotorch/
- tensor/ – Tensor class + low-level ops (nanotorch/tensor).
- nn/ – neural network abstractions (base Module, functional API, container, activation, linear modules, loss functions).
- optim/ – optimizer framework and SGD implementation.
- utils/ – decorators (e.g., dtypes) and other helpers.

##### Extract additional insights from the README
- Highlights the basic workflow: define a Module subclass, use nn.Sequential, build a training loop with MSELoss and SGD on numpy-backed Tensors.
- Demonstrates core components: Tensor, Module, Loss, Optimizer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User scripts and tests
    subgraph "User Code & Tests"
        direction TB
        UserScripts["main.py"]:::user
        TestFile["test.py"]:::user
        TestDir["test/"]:::user
    end

    %% Core Library
    subgraph "Core Library (nanotorch)" 
        direction TB
        subgraph "Tensor Core" 
            direction TB
            TensorClass["tensor.py"]:::core
            TensorOps["ops.py"]:::core
        end
        subgraph "NN Layer API"
            direction TB
            BaseAPI["base.py"]:::core
            FunctionalAPI["functional.py"]:::core
            subgraph "Modules"
                direction TB
                Activations["activations.py"]:::core
                Container["container.py"]:::core
                Linear["linear.py"]:::core
            end
        end
        LossFuncs["loss.py"]:::core
        subgraph "Optimizer Framework"
            direction TB
            OptBase["base.py"]:::core
            SGDOpt["sgd.py"]:::core
        end
        Utils["dtype.py"]:::core
    end

    %% External dependency
    NumPy["NumPy"]:::external

    %% Documentation and CI/CD
    subgraph "Documentation"
        direction TB
        DocsSource["docs/"]:::doc
        MkDocsConfig["mkdocs.yml"]:::doc
        DocsSite["Built Site"]:::doc
    end

    CI[".github/workflows/deploy.yml"]:::doc

    %% Relationships
    UserScripts -->|"calls API"| BaseAPI
    UserScripts -->|"calls API"| FunctionalAPI
    TestFile -->|"tests"| BaseAPI
    TestFile -->|"tests"| TensorClass
    TestDir --> TestFile

    BaseAPI -->|"uses"| TensorClass
    BaseAPI -->|"uses"| TensorOps
    FunctionalAPI -->|"uses"| TensorOps
    Activations -->|"uses"| TensorClass
    Container -->|"contains Modules"| Linear
    Linear -->|"uses"| TensorClass

    BaseAPI -->|"defines forward"| Linear
    Linear -->|"computes output"| LossFuncs
    LossFuncs -->|"computes loss"| TensorOps
    LossFuncs -->|"backprop grads"| TensorOps

    TensorOps -->|"provides arrays"| NumPy
    TensorClass -->|"wraps ndarrays"| NumPy

    TensorOps -->|"grads"| OptBase
    OptBase -->|"implements step"| SGDOpt
    SGDOpt -->|"updates params in"| Container

    %% Documentation build flow
    DocsSource -->|"configured by"| MkDocsConfig
    MkDocsConfig -->|"build site"| DocsSite
    CI -->|"triggers build"| DocsSite

    %% Click events
    click UserScripts "https://github.com/jamormoussa/nanotorch/blob/main/main.py"
    click TestFile "https://github.com/jamormoussa/nanotorch/blob/main/test.py"
    click TestDir "https://github.com/jamormoussa/nanotorch/tree/main/test/"
    click TensorClass "https://github.com/jamormoussa/nanotorch/blob/main/nanotorch/tensor/tensor.py"
    click TensorOps "https://github.com/jamormoussa/nanotorch/blob/main/nanotorch/tensor/ops.py"
    click BaseAPI "https://github.com/jamormoussa/nanotorch/blob/main/nanotorch/nn/base.py"
    click FunctionalAPI "https://github.com/jamormoussa/nanotorch/blob/main/nanotorch/nn/functional.py"
    click Activations "https://github.com/jamormoussa/nanotorch/blob/main/nanotorch/nn/modules/activations.py"
    click Container "https://github.com/jamormoussa/nanotorch/blob/main/nanotorch/nn/modules/container.py"
    click Linear "https://github.com/jamormoussa/nanotorch/blob/main/nanotorch/nn/modules/linear.py"
    click LossFuncs "https://github.com/jamormoussa/nanotorch/blob/main/nanotorch/nn/modules/loss.py"
    click OptBase "https://github.com/jamormoussa/nanotorch/blob/main/nanotorch/optim/base.py"
    click SGDOpt "https://github.com/jamormoussa/nanotorch/blob/main/nanotorch/optim/sgd.py"
    click Utils "https://github.com/jamormoussa/nanotorch/blob/main/nanotorch/utils/_decorators/dtype.py"
    click DocsSource "https://github.com/jamormoussa/nanotorch/tree/main/docs/"
    click MkDocsConfig "https://github.com/jamormoussa/nanotorch/blob/main/mkdocs.yml"
    click CI "https://github.com/jamormoussa/nanotorch/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef user fill:#ccffcc,stroke:#009900,color:#000000
    classDef core fill:#cce5ff,stroke:#0044cc,color:#000000
    classDef external fill:#ffffcc,stroke:#cccc00,color:#000000
    classDef doc fill:#eeeeee,stroke:#666666,color:#000000
```
