How animishmahajan/digit-recognition-using-mlp-network-made-with-numpy works
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: main.py Main app · model.py Model wrapper · nn_npy.py MLP core · Dockerfile.dockerfile Container
Components 16
Application
Runtime web entrypoint and server-rendered UI.
- Browser · User-facing digit input and result display.
- Main app · Runtime entrypoint and request handler.
src/main.py - UI template · Thin browser-facing page for the demo workflow.
src/templates/index.html - Preprocess · Converts submitted input into model-ready data.
src/main.py - Prediction API · High-level prediction workflow exposed by the app.
src/main.py
ML Core
NumPy-based model logic and prediction engine.
- Model wrapper · Loads artifacts and bridges app code to NumPy inference.
src/model.py - MLP core · Manual multilayer perceptron mechanics and learning primitives.
src/nn_npy.py - Forward pass · Computes activations and outputs for prediction.
src/nn_npy.py - Backprop · Manual gradient computation and parameter update logic.
src/nn_npy.py - Activations · Nonlinear layers used by the network.
src/nn_npy.py - Loss · Error computation for training the perceptron.
src/nn_npy.py
Model Artifacts
Persisted trained network state used at inference time.
- Model arch · Serialized network structure for MNIST inference.
models/mnist/model_arch.npz - Weights · Learned weights and biases for the trained model.
models/mnist/params.npz
Packaging
Environment and container support.
- Deps · Runtime package requirements.
requirements.txt - Container · Containerization for reproducible execution.
Dockerfile.dockerfile - MLOps config · Supplementary environment or deployment configuration.
mlops.yaml
Connections 16
- 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.