# knetic0/mnist-live-learning architecture

> Architecture diagram of the GitHub repository knetic0/mnist-live-learning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/knetic0/mnist-live-learning
- Repository: https://github.com/knetic0/mnist-live-learning

## Overview

##### Project type and purpose
- This is a lightweight full-stack web application for on-the-fly training and prediction of MNIST digits.
- The front end is a browser UI (canvas + basic controls) built with HTML/JS/CSS.
- The backend is a Node.js/Express server that handles two REST endpoints (/train, /predict) and uses TensorFlow.js (in train.js) to build, train, predict, and persist a CNN model.

##### File structure
- index.js – Express server setup, routes and middleware.
- train.js – Model architecture definition (CNN layers), train & predict functions, model load/save logic.
- public/ – Front-end assets: index.html (UI), app.js (canvas logic, mode toggling, API calls), styles.css.
- model/ (auto-created) – Filesystem persistence for the TensorFlow.js model.
- package.json / package-lock.json – Dependency and script definitions.
- .env (via .env.example) – Configuration for PORT and MODEL_DIR.
- Scripts: npm start / npm run dev (nodemon).

##### README for insights
- Two main UX flows: Training Mode (POST /train with image+label) and Prediction Mode (POST /predict with image).
- Automatic model persistence every hour and at shutdown.
- TensorFlow.js used both in browser (for canvas preprocessing?) and on server.

##### Main components & interactions
a. Front End
– Browser Canvas UI
– app.js handles user input, mode selection, HTTP calls.
b. API Layer (Express server)
– index.js sets up /train and /predict endpoints
– Receives multipart/form-data (image blob, label)
c. ML Engine (train.js)
– Defines CNN model
– Exposes trainSample() and predictSample()
– On train request: preprocess image → call model.fit()
– On predict request: preprocess → call model.predict()
d. Persistent Storage
– model directory on disk (MODEL_DIR)
– loadModel() at startup if exists
– saveModel() hourly and on shutdown
e. External/Infrastructure
– Environment variables (PORT, MODEL_DIR)
– Node.js runtime
– npm modules (Express, TensorFlow.js)

Browser UI → HTTP POST /train → Express → train.js.trainSample → TensorFlow.js → Model in memory → save to disk
Browser UI → HTTP POST /predict → Express → train.js.predictSample → TensorFlow.js → JSON response → Browser UI

##### Architectural patterns & principles
- Monolithic two-tier design (client/server).
- Separation of concerns:
– UI rendering & event handling (public/)
– HTTP routing & middleware (index.js)
– ML logic & persistence (train.js + model/).
- RESTful endpoints for decoupled client interactions.
- File-based model persistence (no external database).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        CanvasUI["Canvas UI<br>(public/index.html)"]:::frontend
        AppLogic["App Logic<br>(public/app.js)"]:::frontend
        Styles["Styles<br>(public/assets/css/styles.css)"]:::frontend
    end

    %% Server Layer
    subgraph "Server"
        direction TB
        NodeRuntime["Node.js Runtime<br>ENV: PORT, MODEL_DIR"]:::infrastructure
        Express["Express API<br>(index.js)"]:::server
        MLEngine["ML Engine<br>(train.js)"]:::ml
        Scheduler["Cron: Hourly & Shutdown<br>saveModel()"]:::infrastructure
        Config["Config & Dependencies<br>(package.json, package-lock.json, .env)"]:::config
    end

    %% Storage Layer
    subgraph "Storage"
        direction TB
        ModelStorage["Model Storage<br>(model/)"]:::storage
    end

    %% Flow arrows
    CanvasUI -->|"/train" POST| Express
    CanvasUI -->|"/predict" POST| Express
    Express -->|"trainSample()"| MLEngine
    Express -->|"predictSample()"| MLEngine
    MLEngine -->|"loadModel()/saveModel()"| ModelStorage
    Scheduler -->|"saveModel()"| MLEngine
    MLEngine -->|"JSON response"| Express
    Express -->|"Response"| CanvasUI
    NodeRuntime --> Express
    Config --> Express
    Config --> MLEngine

    %% Click Events
    click CanvasUI "https://github.com/knetic0/mnist-live-learning/blob/master/public/index.html"
    click Styles "https://github.com/knetic0/mnist-live-learning/blob/master/public/assets/css/styles.css"
    click Express "https://github.com/knetic0/mnist-live-learning/blob/master/index.js"
    click MLEngine "https://github.com/knetic0/mnist-live-learning/blob/master/train.js"
    click Config "https://github.com/knetic0/mnist-live-learning/blob/master/package.json"
    click Config "https://github.com/knetic0/mnist-live-learning/blob/master/package-lock.json"
    click ModelStorage "https://github.com/knetic0/mnist-live-learning/tree/master/model/"

    %% Styles
    classDef frontend fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef server fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef ml fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef storage fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef config fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef infrastructure fill:#D1C4E9,stroke:#333,stroke-width:1px
```
