# anujkulal/handwritten-equation-solver architecture

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

- Interactive diagram: https://gitdiagram.com/anujkulal/handwritten-equation-solver
- Repository: https://github.com/anujkulal/handwritten-equation-solver

## Overview

##### Project Type and Purpose
- This is a full-stack web application called “handwritten-equation-solver.”
- Frontend: React + TypeScript app (Vite) providing a drawing canvas for users to handwrite equations.
- Backend: Python web service (likely Flask or similar) hosting a pre-trained Keras/TensorFlow model to classify symbols and then solve the equation.

##### File Structure Analysis
- Top level:
- backend/ – Python app, model file (math_symbol_classifier.h5), class_indices.json
- frontend/ – React + TypeScript source, Vite config, HTML entry point
- No databases or external microservices, just a two-tier architecture.
- Configuration files (package.json, tsconfig, eslint) suggest standard React/Vite setup.

##### README Insights
- Two processes: one to start backend (`python app.py`), one to start frontend (`npm run dev`).
- No mention of additional components (e.g. caching, message queues), confirming a simple front-to-back HTTP architecture.

##### Components
a. Main Components
- User’s Browser (UI layer)
- Frontend App
– Drawing Canvas component
– HTTP Client (fetch/axios)
- Backend Service
– Web Framework (Flask/FastAPI)
– Model Loader (loads .h5 file, class_indices.json)
– Symbol Classifier (Keras inference)
– Equation Solver (parses symbols into expression, computes result)
- Static Assets & Model Store (on server filesystem)

b. Relationships & Interactions
1. User draws equation → Canvas component captures strokes → converts to image or pixel data.
2. Frontend sends image payload (e.g., base64) via HTTP POST to backend `/predict` or `/solve` endpoint.
3. Backend receives image, Model Loader initializes the Keras model once at startup.
4. Classifier module runs inference → outputs predicted symbol classes.
5. Solver module assembles symbols into a math expression → computes result.
6. Backend returns JSON response (symbol sequence + solution) to frontend.
7. Frontend displays recognized equation and solution to the user.

c. Architectural Patterns & Design Principles
- Two-tier, client–server separation.
- Single responsibility: frontend does only UI/data collection; backend handles ML and business logic.
- Model is loaded once (singleton pattern) to minimize inference latency.
- Stateless HTTP endpoints for easy scaling (if Dockerized or containerized later).

d. Key Technologies & Libraries
- Frontend: React, TypeScript, Vite dev server, HTML5 Canvas
- Backend: Python 3, Flask (or FastAPI), TensorFlow/Keras
- Model files: math_symbol_classifier.h5, class_indices.json
- Build tools/config: npm, package.json, tsconfig.json

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers vertical
    subgraph "Layer 1: User & Browser"
        direction TB
        User["User"]:::external
        Browser["Browser"]:::external
        User -->|"interacts with"| Browser
    end

    subgraph "Layer 2: React Frontend" 
        direction TB
        Canvas["Canvas Component"]:::frontend
        HTTPClient["HTTP Client"]:::frontend
        Canvas -->|"captures strokes"| HTTPClient
    end

    subgraph "Layer 3: HTTP API"
        direction TB
        PredictEndpoint["POST /predict"]:::backend
    end

    subgraph "Layer 4: Python Backend"
        direction TB
        WebFramework["Flask/FastAPI App"]:::backend
        ModelLoader["Model Loader"]:::backend
        Classifier["Symbol Classifier"]:::backend
        Solver["Equation Solver"]:::backend
        PredictEndpoint -->|"routes to"| WebFramework
        WebFramework -->|"loads at startup"| ModelLoader
        WebFramework -->|"handles request"| Classifier
        Classifier -.->|"internal call"| Solver
        Solver -->|"returns result"| WebFramework
        WebFramework -->|"JSON response"| PredictEndpoint
    end

    subgraph "Layer 5: ML Artifacts & Files"
        direction TB
        ModelFile["math_symbol_classifier.h5"]:::ml
        ClassJSON["class_indices.json"]:::data
        ModelLoader -->|"loads"| ModelFile
        ModelLoader -->|"loads"| ClassJSON
    end

    %% Frontend to Backend
    Browser -->|"POST base64 image"| PredictEndpoint
    PredictEndpoint -->|"JSON response"| Browser
    HTTPClient -->|"calls POST /predict"| PredictEndpoint

    %% Click Events
    click App_ts "https://github.com/anujkulal/handwritten-equation-solver/blob/main/frontend/src/App.tsx"
    click IndexHTML "https://github.com/anujkulal/handwritten-equation-solver/blob/main/frontend/index.html"
    click ViteConfig "https://github.com/anujkulal/handwritten-equation-solver/blob/main/frontend/vite.config.ts"
    click Canvas "https://github.com/anujkulal/handwritten-equation-solver/blob/main/frontend/src/App.tsx"
    click WebFramework "https://github.com/anujkulal/handwritten-equation-solver/blob/main/backend/app.py"
    click ModelLoader "https://github.com/anujkulal/handwritten-equation-solver/blob/main/backend/app.py"
    click Classifier "https://github.com/anujkulal/handwritten-equation-solver/blob/main/backend/app.py"
    click Solver "https://github.com/anujkulal/handwritten-equation-solver/blob/main/backend/app.py"
    click ModelFile "https://github.com/anujkulal/handwritten-equation-solver/blob/main/backend/math_symbol_classifier.h5"
    click ClassJSON "https://github.com/anujkulal/handwritten-equation-solver/blob/main/backend/class_indices.json"

    %% Styles
    classDef frontend fill:#B3D1FF,stroke:#0366d6,color:#000;
    classDef backend fill:#B3FFD1,stroke:#28a745,color:#000;
    classDef ml fill:#FFD1B3,stroke:#db8b0b,color:#000;
    classDef data fill:#D3D3D3,stroke:#6c757d,color:#000;
    classDef external fill:#E0E0E0,stroke:#343a40,color:#000;
```
