# faizanmasroor/handmade-neural-network architecture

> Architecture diagram of the GitHub repository faizanmasroor/handmade-neural-network, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/faizanmasroor/handmade-neural-network
- Repository: https://github.com/faizanmasroor/handmade-neural-network

## Overview

This is an educational, from-scratch MNIST digit classifier. The documented workflow is to supply MNIST CSV files, load and preprocess the data, train or load a network, evaluate it, and optionally draw a digit for prediction. The sampled code supports these stages and the matrix-utility layer; several responsibilities share neural_network.py. The interactive entry-point code is only partly excerpted, so its broader wiring is not inferred.

Main entry points: [`neural_network.py`](https://github.com/faizanmasroor/handmade-neural-network/blob/main/neural_network.py) (Classifier runtime), [`matrix_math.py`](https://github.com/faizanmasroor/handmade-neural-network/blob/main/matrix_math.py) (Matrix and loss math), [`data.py`](https://github.com/faizanmasroor/handmade-neural-network/blob/main/data.py) (Data loader), [`pickles`](https://github.com/faizanmasroor/handmade-neural-network/tree/main/pickles) (Prepared dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["MNIST workflow"]
  node_app["Classifier runtime<br/>[neural_network.py]"]
  node_loader["Data loader<br/>[data.py]"]
  node_dataset[("Prepared dataset")]
  node_drawing["Digit drawing<br/>[neural_network.py]"]
end

subgraph group_ml["Network and math"]
  node_training["Network training<br/>[neural_network.py]"]
  node_evaluation["Accuracy evaluation<br/>[neural_network.py]"]
  node_prediction["Digit prediction<br/>[neural_network.py]"]
  node_math["Matrix and loss math<br/>[matrix_math.py]"]
end

node_user(("User"))
node_mnist["MNIST CSV"]

node_user -->|"downloads"| node_mnist
node_user -->|"uses"| node_app
node_mnist -->|"provides CSV"| node_loader
node_app -->|"loads data"| node_loader
node_loader -->|"encodes labels"| node_math
node_app -->|"caches data"| node_dataset
node_app -->|"trains or loads"| node_training
node_training -->|"uses activation and loss"| node_math
node_app -->|"tests model"| node_evaluation
node_evaluation -->|"decodes predictions"| node_math
node_user -->|"draws digit"| node_drawing
node_drawing -->|"prepares input for"| node_prediction
node_prediction -->|"decodes output"| node_math

click node_app "https://github.com/faizanmasroor/handmade-neural-network/blob/main/neural_network.py"
click node_loader "https://github.com/faizanmasroor/handmade-neural-network/blob/main/data.py"
click node_dataset "https://github.com/faizanmasroor/handmade-neural-network/tree/main/pickles"
click node_training "https://github.com/faizanmasroor/handmade-neural-network/blob/main/neural_network.py"
click node_evaluation "https://github.com/faizanmasroor/handmade-neural-network/blob/main/neural_network.py"
click node_drawing "https://github.com/faizanmasroor/handmade-neural-network/blob/main/neural_network.py"
click node_prediction "https://github.com/faizanmasroor/handmade-neural-network/blob/main/neural_network.py"
click node_math "https://github.com/faizanmasroor/handmade-neural-network/blob/main/matrix_math.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_loader,node_dataset,node_drawing,node_user toneBlue
class node_training,node_evaluation,node_prediction,node_math toneAmber
class node_mnist toneIndigo
```

## Components

### MNIST workflow

- [Classifier runtime](https://github.com/faizanmasroor/handmade-neural-network/blob/main/neural_network.py): `neural_network.py`
- [Data loader](https://github.com/faizanmasroor/handmade-neural-network/blob/main/data.py): `data.py`
- [Prepared dataset](https://github.com/faizanmasroor/handmade-neural-network/tree/main/pickles): `pickles`
- [Digit drawing](https://github.com/faizanmasroor/handmade-neural-network/blob/main/neural_network.py): `neural_network.py`

### Network and math

- [Network training](https://github.com/faizanmasroor/handmade-neural-network/blob/main/neural_network.py): `neural_network.py`
- [Accuracy evaluation](https://github.com/faizanmasroor/handmade-neural-network/blob/main/neural_network.py): `neural_network.py`
- [Digit prediction](https://github.com/faizanmasroor/handmade-neural-network/blob/main/neural_network.py): `neural_network.py`
- [Matrix and loss math](https://github.com/faizanmasroor/handmade-neural-network/blob/main/matrix_math.py): `matrix_math.py`

### Other components

- **User**
- **MNIST CSV**

## Connections

- User → MNIST CSV: downloads (evidence: `README.md`)
- User → Classifier runtime: uses (evidence: `README.md`)
- MNIST CSV → Data loader: provides CSV (evidence: `README.md`)
- Classifier runtime → Data loader: loads data (evidence: `neural_network.py`)
- Data loader → Matrix and loss math: encodes labels (evidence: `data.py`)
- Classifier runtime → Prepared dataset: caches data (evidence: `neural_network.py`)
- Classifier runtime → Network training: trains or loads (evidence: `neural_network.py`)
- Network training → Matrix and loss math: uses activation and loss (evidence: `neural_network.py`)
- Classifier runtime → Accuracy evaluation: tests model (evidence: `neural_network.py`)
- Accuracy evaluation → Matrix and loss math: decodes predictions (evidence: `neural_network.py`)
- User → Digit drawing: draws digit (evidence: `README.md`)
- Digit drawing → Digit prediction: prepares input for (evidence: `neural_network.py`)
- Digit prediction → Matrix and loss math: decodes output (evidence: `neural_network.py`)
