# arceusomkar7/digit-recognizer architecture

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

- Interactive diagram: https://gitdiagram.com/arceusomkar7/digit-recognizer
- Repository: https://github.com/arceusomkar7/digit-recognizer

## Overview

##### Project type and purpose
- This is a lightweight full-stack web application (“Digit Recognizer”) that uses FastAPI on the backend to serve a single-page front-end (HTML + Tailwind + Canvas API). It exposes endpoints for accepting drawn or uploaded images and returning digit predictions powered by pre-trained scikit-learn models (KNN, SVM, etc.).

##### File structure
- Top level:
- run.py – entry script to launch the app (likely wraps uvicorn).
- requirements.txt – Python dependencies (FastAPI, joblib, scikit-learn, etc.).
- mnist.ipynb – exploratory notebook (development only).
- models/ – directory holding serialized model artifacts (joblib files).
- app/ – main application package:
– main.py – FastAPI app, routing, prediction logic.
– static/ – contains index.html (front-end assets; could host CSS/JS).
- No database or external microservices—pure in-memory ML inference.

##### README
- Confirms FastAPI backend, HTML/Tailwind/CANVAS front end, running via uvicorn.
- Describes usage flow: user draws or uploads image → choose model → see result.
- Lists dependencies and performance metrics for KNN and SVM.

a. Main components
- Client (Browser) – runs index.html, Canvas API + Tailwind UI.
- FastAPI Server – HTTP API endpoints: /home (serves UI), /predict (accepts image + model choice).
- Model Loader & Predictor – loads .joblib files from models/ on startup or per request; handles preprocessing.
- Joblib Models – KNN, SVM (and any others) serialized in models/.
- (Optional) Development Notebook – separate component for data exploration; not in production.

b. Relationships and interactions
- Browser → (HTTP POST) → /predict endpoint, sending image payload + model parameter.
- FastAPI → Model Loader → selected .joblib model → Prediction result.
- FastAPI → HTTP Response → JSON { digit: n, confidence: x }.
- Browser ← Response ← displays result on canvas/UI.
- Browser requests index.html and any CSS/JS via HTTP GET at /home (or root).

c. Architectural patterns
- MVC-like separation:
– V (View): static HTML/CSS/JS in app/static.
– C (Controller): FastAPI routes in main.py.
– M (Model): ML model artifacts (.joblib) + prediction logic.
- Single service (monolith), no external DB.
- Pre-trained models loaded at startup for low-latency inference.

d. Key technologies
- FastAPI (Python web framework)
- Uvicorn (ASGI server)
- scikit-learn, joblib (model serialization/inference)
- HTML + Tailwind CSS + Canvas API (frontend)

##### Essential elements
- Component labels (e.g., “Canvas API”, “SVM Model.joblib”).
- Optional: annotate ports (8000) and file locations (app/static, models/).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Browser)"
        UI["Browser UI\n(index.html)"]:::frontend
        Canvas["Canvas API"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Server)"
        API["FastAPI Server\n(app/main.py)"]:::backend
        Loader["Model Loader & Predictor\n(app/main.py)"]:::inference
        Models["Model Artifacts\n(models/*.joblib)"]:::storage
    end

    %% Utility Components
    run["Entry Script\n(run.py)"]:::backend
    deps["Dependencies\n(requirements.txt)"]:::utility
    notebook["Dev Notebook\n(mnist.ipynb)"]:::utility

    %% Connections
    UI -->|"GET /"| API
    Canvas -->|"POST /predict"| API
    API -->|"load model"| Loader
    Loader -->|"loads .joblib"| Models
    Loader -->|"predict()"| API
    API -->|"return JSON"| UI
    run -->|"starts"| API
    deps -->|"installs"| run
    notebook -.->|"dev only"| Models

    %% Click Events
    click UI "https://github.com/arceusomkar7/digit-recognizer/blob/main/app/static/index.html"
    click API "https://github.com/arceusomkar7/digit-recognizer/blob/main/app/main.py"
    click Loader "https://github.com/arceusomkar7/digit-recognizer/blob/main/app/main.py"
    click Models "https://github.com/arceusomkar7/digit-recognizer/blob/main/models/random_forest_clf.joblib"
    click run "https://github.com/arceusomkar7/digit-recognizer/blob/main/run.py"
    click deps "https://github.com/arceusomkar7/digit-recognizer/blob/main/requirements.txt"
    click notebook "https://github.com/arceusomkar7/digit-recognizer/blob/main/mnist.ipynb"

    %% Styles
    classDef frontend fill:#bfdbfe,stroke:#1e3a8a,color:#1e3a8a;
    classDef backend fill:#bbf7d0,stroke:#166534,color:#166534;
    classDef inference fill:#fdba74,stroke:#b45309,color:#7c2d12;
    classDef storage fill:#fde047,stroke:#b45309,color:#92400e;
    classDef utility fill:#f0ead6,stroke:#6b7280,color:#6b7280;
```
