# gbennnn/realtime-digit-recognition architecture

> Architecture diagram of the GitHub repository gbennnn/realtime-digit-recognition, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gbennnn/realtime-digit-recognition
- Repository: https://github.com/gbennnn/realtime-digit-recognition

## Overview

#### Purpose and execution modes
This repository serves realtime MNIST handwritten-digit recognition. It has two primary entry points:
- Training: `train_mnist.py` downloads MNIST, trains a TensorFlow/Keras CNN, and writes a reusable model artifact.
- Serving: `app.py` runs a Flask application that loads the trained artifact and exposes browser-driven inference.

#### Model lifecycle
The training pipeline in `train_mnist.py` defines and fits the CNN: two convolution/pooling stages followed by dense classification layers for digits 0–9. TensorFlow is the material ML runtime and MNIST is obtained externally through its dataset loader. The resulting deployable artifact is `models/mnist_cnn.h5`.

#### Flask inference boundary
`app.py` is the server-side integration point between HTTP clients and TensorFlow inference. It renders the application UI and owns the `/predict` endpoint. The endpoint accepts the drawing representation, applies MNIST-oriented image preparation—cropping, scaling, and padding—and returns prediction data to the client. The model file boundary is `models/mnist_cnn.h5`.

#### Browser drawing and realtime request flow
The UI is composed of `templates/index.html`, `static/script.js`, and `static/style.css`. The HTML hosts the canvas and prediction display; browser JavaScript captures drawing input, serializes the canvas image, and issues repeated requests to Flask while the user draws. Response data updates the displayed predicted digit, creating the realtime interaction loop.

#### Input normalization contract
The key compatibility boundary is between canvas output and the model’s expected MNIST-like tensor. Client-produced drawings are not directly equivalent to MNIST samples, so server preprocessing in `app.py` normalizes geometry via foreground cropping, resizing, and padding before model invocation. Training input conventions established in `train_mnist.py` must remain aligned with this inference preprocessing.

#### Runtime and deployment shape
The app is a local Python 3.10+ process using Flask 3.1 and TensorFlow 2.19, with dependencies defined in `requirements.txt`. It has no separate database, queue, or cloud service dependency. Runtime availability depends on the trained H5 artifact being present at `models/mnist_cnn.h5`; retraining/regeneration is handled by `train_mnist.py`.

Main entry points: [`train_mnist.py`](https://github.com/gbennnn/realtime-digit-recognition/blob/main/train_mnist.py) (CNN training), [`app.py`](https://github.com/gbennnn/realtime-digit-recognition/blob/main/app.py) (/predict endpoint), [`templates/index.html`](https://github.com/gbennnn/realtime-digit-recognition/blob/main/templates/index.html) (Canvas page), [`static/script.js`](https://github.com/gbennnn/realtime-digit-recognition/blob/main/static/script.js) (Drawing client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Training pipeline"]
  node_mnist[("MNIST dataset<br/>external dataset")]
  node_trainer["CNN training<br/>Python training entry point<br/>[train_mnist.py]"]
end

subgraph group_serving["Flask serving"]
  node_flask_app["Flask inference app<br/>Python serving entry point<br/>[app.py]"]
  node_preprocessing["MNIST image preparation<br/>inference layer<br/>[app.py]"]
  node_predict_api["/predict endpoint<br/>HTTP endpoint<br/>[app.py]"]
end

subgraph group_browser["Browser UI"]
  node_html["Canvas page<br/>HTML template<br/>[index.html]"]
  node_script["Drawing client<br/>browser JavaScript<br/>[script.js]"]
  node_styles["UI styles<br/>stylesheet<br/>[style.css]"]
end

node_tensorflow["TensorFlow/Keras<br/>ML runtime"]
node_model["Trained CNN artifact<br/>H5 model<br/>[mnist_cnn.h5]"]
node_requirements["Python dependencies<br/>dependency manifest<br/>[requirements.txt]"]

node_mnist -->|"loaded for training"| node_trainer
node_tensorflow -->|"trains CNN"| node_trainer
node_trainer -->|"writes artifact"| node_model
node_requirements -.->|"provides Flask runtime"| node_flask_app
node_requirements -.->|"provides ML runtime"| node_tensorflow
node_model -->|"loaded at startup"| node_flask_app
node_html -->|"rendered by"| node_flask_app
node_styles -->|"styles"| node_html
node_html -->|"loads"| node_script
node_script -->|"repeated canvas requests"| node_predict_api
node_predict_api -->|"drawing payload"| node_preprocessing
node_preprocessing -->|"MNIST-like tensor"| node_tensorflow
node_tensorflow -->|"prediction result"| node_predict_api
node_predict_api -->|"prediction data"| node_script
node_trainer -.->|"shares input convention"| node_preprocessing

click node_trainer "https://github.com/gbennnn/realtime-digit-recognition/blob/main/train_mnist.py"
click node_model "https://github.com/gbennnn/realtime-digit-recognition/blob/main/models/mnist_cnn.h5"
click node_flask_app "https://github.com/gbennnn/realtime-digit-recognition/blob/main/app.py"
click node_preprocessing "https://github.com/gbennnn/realtime-digit-recognition/blob/main/app.py"
click node_predict_api "https://github.com/gbennnn/realtime-digit-recognition/blob/main/app.py"
click node_html "https://github.com/gbennnn/realtime-digit-recognition/blob/main/templates/index.html"
click node_script "https://github.com/gbennnn/realtime-digit-recognition/blob/main/static/script.js"
click node_styles "https://github.com/gbennnn/realtime-digit-recognition/blob/main/static/style.css"
click node_requirements "https://github.com/gbennnn/realtime-digit-recognition/blob/main/requirements.txt"

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_mnist,node_trainer toneBlue
class node_flask_app,node_preprocessing,node_predict_api toneAmber
class node_html,node_script,node_styles toneMint
class node_tensorflow,node_model,node_requirements toneNeutral
```

## Components

### Training pipeline

- **MNIST dataset**: external dataset
- [CNN training](https://github.com/gbennnn/realtime-digit-recognition/blob/main/train_mnist.py): Python training entry point · Defines and fits the digit classifier. · `train_mnist.py`

### Flask serving

- [Flask inference app](https://github.com/gbennnn/realtime-digit-recognition/blob/main/app.py): Python serving entry point · Renders the UI and owns /predict preprocessing and inference. · `app.py`
- [MNIST image preparation](https://github.com/gbennnn/realtime-digit-recognition/blob/main/app.py): inference layer · Crops, rescales, and pads canvas drawings into model input. · `app.py`
- [/predict endpoint](https://github.com/gbennnn/realtime-digit-recognition/blob/main/app.py): HTTP endpoint · `app.py`

### Browser UI

- [Canvas page](https://github.com/gbennnn/realtime-digit-recognition/blob/main/templates/index.html): HTML template · Hosts the drawing canvas and prediction display. · `templates/index.html`
- [Drawing client](https://github.com/gbennnn/realtime-digit-recognition/blob/main/static/script.js): browser JavaScript · Captures strokes, serializes canvas data, and updates predictions. · `static/script.js`
- [UI styles](https://github.com/gbennnn/realtime-digit-recognition/blob/main/static/style.css): stylesheet · `static/style.css`

### Other components

- **TensorFlow/Keras**: ML runtime
- [Trained CNN artifact](https://github.com/gbennnn/realtime-digit-recognition/blob/main/models/mnist_cnn.h5): H5 model · Reusable digit classifier required by serving. · `models/mnist_cnn.h5`
- [Python dependencies](https://github.com/gbennnn/realtime-digit-recognition/blob/main/requirements.txt): dependency manifest · Pins Flask and TensorFlow runtime dependencies. · `requirements.txt`

## Connections

- MNIST dataset → CNN training: loaded for training
- TensorFlow/Keras → CNN training: trains CNN
- CNN training → Trained CNN artifact: writes artifact
- Python dependencies → Flask inference app: provides Flask runtime
- Python dependencies → TensorFlow/Keras: provides ML runtime
- Trained CNN artifact → Flask inference app: loaded at startup
- Canvas page → Flask inference app: rendered by
- UI styles → Canvas page: styles
- Canvas page → Drawing client: loads
- Drawing client → /predict endpoint: repeated canvas requests
- /predict endpoint → MNIST image preparation: drawing payload
- MNIST image preparation → TensorFlow/Keras: MNIST-like tensor
- TensorFlow/Keras → /predict endpoint: prediction result
- /predict endpoint → Drawing client: prediction data
- CNN training → MNIST image preparation: shares input convention