# animishmahajan/digit-recognition-using-mlp-network-made-with-numpy architecture

> Architecture diagram of the GitHub repository animishmahajan/digit-recognition-using-mlp-network-made-with-numpy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy
- Repository: https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy

## Overview

1. **What this repo is**
   - A handwritten digit recognition project built around a **multilayer perceptron implemented manually with NumPy**.
   - The repository combines a small ML core, a web-facing entrypoint, and saved model artifacts for MNIST-style inference.

2. **Main architectural split**
   - The code is divided into two major boundaries:
     - **ML computation layer**: pure NumPy neural-network logic.
     - **Application/UI layer**: a lightweight Python web app with an HTML template.
   - This separation keeps the math/model code isolated from request handling and presentation.

3. **Entry point and serving**
   - `src/main.py` is the runtime entrypoint.
   - The README shows it can run either as a script or as an ASGI app via `uvicorn src.main:app`, so the app is served through a Python web server boundary.
   - This file likely wires together request handling, preprocessing, prediction, and template rendering.

4. **Neural network implementation**
   - `src/nn_npy.py` is the low-level implementation of the MLP.
   - Based on the README, this is where the core mechanics live: matrix operations, forward propagation, activation functions, loss computation, and manual backpropagation/gradient descent.
   - This is the repository’s main “engine” and depends only on NumPy rather than a deep learning framework.

5. **Model orchestration**
   - `src/model.py` likely wraps the raw NumPy network into a higher-level model interface.
   - It is the layer that probably loads the trained parameters, applies the architecture definition, and exposes prediction-oriented methods used by `main.py`.
   - This file is the bridge between the serving code and the math primitives.

6. **Persisted model artifacts**
   - `models/mnist/model_arch.npz` and `models/mnist/params.npz` are the saved artifacts for the trained model.
   - The architecture file stores the network structure; the params file stores learned weights/biases.
   - These files form a clear boundary between **training-time state** and **runtime inference**.

7. **Web presentation layer**
   - `src/templates/index.html` is the browser-facing UI.
   - It appears to be a server-rendered page used for digit input/display, likely supporting the demo workflow rather than acting as a full SPA.
   - The README notes the templates were generated with Gemini, which is relevant only insofar as the HTML is a thin presentation layer.

8. **End-to-end data flow**
   - User accesses the page in the browser.
   - `main.py` receives the request and preprocesses the submitted digit image/input.
   - `model.py` loads the persisted architecture and parameters.
   - `nn_npy.py` performs the forward pass with NumPy.
   - The predicted digit is returned to the template for display.

9. **Training vs inference**
   - The repository contents strongly suggest it is primarily an **inference/demo package** with the trained model already checked in.
   - The README emphasizes manual backpropagation and gradient descent, but no separate training pipeline is visible in the tree.
   - For architecture diagrams, it’s safest to treat training logic as embedded in the NumPy model code rather than as a standalone service.

10. **Deployment and reproducibility**
   - `requirements.txt` defines Python dependencies.
   - `Dockerfile.dockerfile` provides containerization for consistent execution.
   - `mlops.yaml` suggests some environment or deployment automation/configuration, but there is no evidence of a larger distributed platform in the repo itself.

11. **External dependencies**
   - The core ML stack is intentionally minimal: **Python + NumPy**.
   - There is no visible database, message queue, or third-party model serving system.
   - The only notable runtime tooling exposed in the README is `uvicorn` for serving the app.

12. **What to draw in an architecture diagram**
   - Show a **browser/UI layer** feeding into a **Python web app**.
   - Inside the app, separate **request/preprocessing**, **model loading**, and **NumPy inference logic**.
   - Show **model artifacts on disk** as a distinct storage boundary consumed by the model layer.
   - Optionally show **Docker/requirements** as packaging/deployment support around the app rather than as part of the runtime path.

Main entry points: [`src/main.py`](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/main.py) (Main app), [`src/model.py`](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/model.py) (Model wrapper), [`src/nn_npy.py`](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/nn_npy.py) (MLP core), [`Dockerfile.dockerfile`](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/Dockerfile.dockerfile) (Container)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_browser(("Browser<br/>user client"))
  node_main["Main app<br/>web entrypoint<br/>[main.py]"]
  node_template["UI template<br/>server-rendered HTML<br/>[index.html]"]
  node_preprocess["Preprocess<br/>input transform<br/>[main.py]"]
  node_predict_api["Prediction API<br/>app service<br/>[main.py]"]
end

subgraph group_ml["ML Core"]
  node_model_wrap["Model wrapper<br/>model facade<br/>[model.py]"]
  node_net_core["MLP core<br/>NumPy network<br/>[nn_npy.py]"]
  node_forward["Forward pass<br/>inference step<br/>[nn_npy.py]"]
  node_backprop["Backprop<br/>training step<br/>[nn_npy.py]"]
  node_activations["Activations<br/>math ops<br/>[nn_npy.py]"]
  node_loss["Loss<br/>objective<br/>[nn_npy.py]"]
end

subgraph group_artifacts["Model Artifacts"]
  node_arch[("Model arch<br/>saved architecture<br/>[model_arch.npz]")]
  node_params[("Weights<br/>saved parameters<br/>[params.npz]")]
end

subgraph group_packaging["Packaging"]
  node_requirements["Deps<br/>python dependencies<br/>[requirements.txt]"]
  node_dockerfile["Container"]
  node_mlops["MLOps config<br/>deployment config<br/>[mlops.yaml]"]
end

node_browser -->|"submit digit"| node_main
node_main -->|"prepare input"| node_preprocess
node_preprocess -->|"call predict"| node_predict_api
node_predict_api -->|"invoke model"| node_model_wrap
node_main -->|"render page"| node_template
node_model_wrap -->|"load arch"| node_arch
node_model_wrap -->|"load weights"| node_params
node_model_wrap -->|"use engine"| node_net_core
node_net_core -->|"run inference"| node_forward
node_forward -->|"apply nonlinearities"| node_activations
node_backprop -->|"measure error"| node_loss
node_backprop -->|"update params"| node_net_core
node_main -->|"predict"| node_model_wrap
node_dockerfile -->|"install deps"| node_requirements
node_dockerfile -->|"run app"| node_main
node_mlops -.->|"configure runtime"| node_main

click node_main "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/main.py"
click node_template "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/templates/index.html"
click node_preprocess "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/main.py"
click node_predict_api "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/main.py"
click node_model_wrap "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/model.py"
click node_net_core "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/nn_npy.py"
click node_forward "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/nn_npy.py"
click node_backprop "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/nn_npy.py"
click node_activations "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/nn_npy.py"
click node_loss "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/nn_npy.py"
click node_arch "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/models/mnist/model_arch.npz"
click node_params "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/models/mnist/params.npz"
click node_requirements "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/requirements.txt"
click node_dockerfile "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/Dockerfile.dockerfile"
click node_mlops "https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/mlops.yaml"

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_browser,node_main,node_template,node_preprocess,node_predict_api toneBlue
class node_model_wrap,node_net_core,node_forward,node_backprop,node_activations,node_loss toneAmber
class node_arch,node_params toneMint
class node_requirements,node_dockerfile,node_mlops toneRose
```

## Components

### Application

Runtime web entrypoint and server-rendered UI.

- **Browser**: user client · User-facing digit input and result display.
- [Main app](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/main.py): web entrypoint · Runtime entrypoint and request handler. · `src/main.py`
- [UI template](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/templates/index.html): server-rendered HTML · Thin browser-facing page for the demo workflow. · `src/templates/index.html`
- [Preprocess](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/main.py): input transform · Converts submitted input into model-ready data. · `src/main.py`
- [Prediction API](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/main.py): app service · High-level prediction workflow exposed by the app. · `src/main.py`

### ML Core

NumPy-based model logic and prediction engine.

- [Model wrapper](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/model.py): model facade · Loads artifacts and bridges app code to NumPy inference. · `src/model.py`
- [MLP core](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/nn_npy.py): NumPy network · Manual multilayer perceptron mechanics and learning primitives. · `src/nn_npy.py`
- [Forward pass](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/nn_npy.py): inference step · Computes activations and outputs for prediction. · `src/nn_npy.py`
- [Backprop](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/nn_npy.py): training step · Manual gradient computation and parameter update logic. · `src/nn_npy.py`
- [Activations](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/nn_npy.py): math ops · Nonlinear layers used by the network. · `src/nn_npy.py`
- [Loss](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/src/nn_npy.py): objective · Error computation for training the perceptron. · `src/nn_npy.py`

### Model Artifacts

Persisted trained network state used at inference time.

- [Model arch](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/models/mnist/model_arch.npz): saved architecture · Serialized network structure for MNIST inference. · `models/mnist/model_arch.npz`
- [Weights](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/models/mnist/params.npz): saved parameters · Learned weights and biases for the trained model. · `models/mnist/params.npz`

### Packaging

Environment and container support.

- [Deps](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/requirements.txt): python dependencies · Runtime package requirements. · `requirements.txt`
- [Container](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/Dockerfile.dockerfile): container build · Containerization for reproducible execution. · `Dockerfile.dockerfile`
- [MLOps config](https://github.com/animishmahajan/digit-recognition-using-mlp-network-made-with-numpy/blob/main/mlops.yaml): deployment config · Supplementary environment or deployment configuration. · `mlops.yaml`

## Connections

- Browser → Main app: submit digit · Browser sends input to the web app.
- Main app → Preprocess: prepare input · The app normalizes and shapes submitted data.
- Preprocess → Prediction API: call predict · Prepared input enters the prediction workflow.
- Prediction API → Model wrapper: invoke model · Application delegates prediction to the model layer.
- Main app → UI template: render page · The app returns server-rendered HTML.
- Model wrapper → Model arch: load arch · Model wrapper reads the saved architecture.
- Model wrapper → Weights: load weights · Model wrapper reads learned parameters.
- Model wrapper → MLP core: use engine · Wrapper delegates computation to the NumPy network.
- MLP core → Forward pass: run inference · Core network computes predictions.
- Forward pass → Activations: apply nonlinearities · Forward pass uses activation functions.
- Backprop → Loss: measure error · Training logic depends on the loss function.
- Backprop → MLP core: update params · Gradient updates modify the network state.
- Main app → Model wrapper: predict · Entrypoint connects requests to the model facade.
- Container → Deps: install deps · Container build relies on the Python dependency set.
- Container → Main app: run app · Container image launches the web entrypoint.
- MLOps config → Main app: configure runtime · Deployment config supports running the app.