# mahender-reddy85/advanced-calculator architecture

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

- Interactive diagram: https://gitdiagram.com/mahender-reddy85/advanced-calculator
- Repository: https://github.com/mahender-reddy85/advanced-calculator

## Overview

##### Project type & purpose (what you’re diagramming)
This is a **small full-stack web application**:
- **Frontend**: Static HTML/CSS/Vanilla JS UI that implements calculator modes (basic/scientific/graphing) and export/pretty rendering.
- **Backend**: **Node.js + Express** API that proxies requests to **Google Gemini** for the “AI-powered solver”.
- **No first-party database** appears in the tree (no DB drivers/config); persistence is likely client-side only (or not implemented).

- Browser-based app + client libraries (Chart.js, MathJax, Math.js, jsPDF)
- Express server endpoints
- External Gemini API integration
- Data flows for “calculate locally” vs “solve via AI”.

##### File structure cues (map code → components)
From the file tree:

##### Frontend (`/frontend`)
- `index.html`: entry point; likely loads scripts + defines UI layout
- `calculator.js`: core client logic (mode switching, expression parsing, charting calls, AI request calls, export)
- `calculator.css`: styling, responsive UI, themes

##### Backend (`/backend`)
- `server.js`: Express app definition + routes; likely includes:
- CORS
- dotenv (reads `GEMINI_API_KEY`, `PORT`)
- node-fetch (calls Gemini API)
- `package.json/package-lock.json`: confirms Express/CORS/dotenv/node-fetch dependencies and scripts

##### Root
- README describes runtime model: backend runs on a port; frontend opened separately (file:// or Live Server)

This implies a **two-process dev setup**:
- Static frontend served by Live Server (or directly opened)
- Express server running separately, used only for AI solving calls

##### What the README reveals (runtime dependencies & responsibilities)
Key architectural responsibilities:
- **Local computation**: handled in-browser (Math.js)
- **Graphing**: client-side rendering (Chart.js)
- **Math rendering**: client-side typesetting (MathJax)
- **PDF export**: client-side (jsPDF)
- **AI step-by-step solving**: requires backend, which holds secret `GEMINI_API_KEY` and calls Gemini

Important: show **why** the backend exists: **to keep the API key off the client** and to centralize Gemini calls (plus CORS/security).

##### Browser / Frontend Web App
- `index.html` (UI shell)
- `calculator.js` (client controller/logic)
- `calculator.css` (presentation)
- Client libraries:
- **Math.js** (compute engine)
- **Chart.js** (graph renderer)
- **MathJax** (formula typesetter)
- **jsPDF** (export)
##### Backend API (Node.js + Express)
- `server.js`
- middleware: CORS, dotenv
- HTTP client: node-fetch
##### Configuration/Secrets
- `.env` (GEMINI_API_KEY, PORT) — show as attached to backend only

- “Internet” boundary between backend and Gemini

##### Flow 1: Basic/Scientific calculations (local-only)
- User → Browser UI
- Browser UI → `calculator.js`
- `calculator.js` → **Math.js** (evaluate expression)
- Result → UI render (optionally MathJax for formatting)

**No backend involved**. Make this visually clear (it’s part of the value: low latency/offline-like behavior).

##### Flow 2: Graphing (local-only)
- User enters function → `calculator.js`
- `calculator.js` → Math.js (evaluate y for x samples)
- `calculator.js` → Chart.js (render graph on canvas)
- UI interactions (pan/zoom) remain in-browser

##### Flow 3: AI-powered solver (client → backend → Gemini)
- User submits natural language problem in Browser
- Browser (`calculator.js`) → HTTP request → **Express endpoint** (e.g., `/api/solve`)
- Express (`server.js`) → node-fetch → **Gemini API**
- Gemini API → response with steps/explanations → Express
- Express → JSON result → Browser
- Browser → display steps (optionally MathJax typesets)

##### Flow 4: Export (local-only)
- Browser (`calculator.js`) → jsPDF → downloads PDF

##### Architectural patterns/principles present

- **Thin backend / BFF-like proxy**: backend is primarily an API façade for Gemini and secret management.
- **Client-heavy architecture**: core computation, graphing, formatting, and export happen in the browser.
- **Separation of concerns**:
- UI/UX in HTML/CSS
- Orchestration in `calculator.js`
- AI integration & secrets in backend
- **External dependency boundary**: Gemini is outside your trust boundary; backend mediates access.

##### Relevant tech labels (don’t leave them implicit)
- Frontend: “Vanilla JS + Chart.js + MathJax + Math.js + jsPDF”
- Backend: “Node.js + Express + CORS + dotenv + node-fetch”
- External: “Google Gemini API”

##### What to explicitly include
For maximum accuracy and usefulness:

##### Labels
- Use concrete labels like:
- “GET/POST /api/solve”
- “Gemini prompt request”
- “JSON response: steps + explanation”
- “Local eval (Math.js)”
- “Render graph (Chart.js)”

- User
- Browser app (frontend)
- Backend API (Express)
- Gemini API
- Boundaries: Client device vs Server vs External

This reveals that 80% of the app is client-side, and only AI solving goes to the backend.

- Backend internal view: Express route → prompt construction → fetch Gemini → response mapping → return JSON
- Dotenv + GEMINI_API_KEY usage explicitly

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Diagram 1: Container View
    %% =========================

    U["User"]:::external

    subgraph CDEV["Client Device / Browser Runtime"]
        B["Browser"]:::client
        subgraph FE["Frontend Web App (Static Assets)"]
            FE_HTML["index.html (UI shell)"]:::frontend
            FE_JS["calculator.js (client controller)"]:::frontend
            FE_CSS["calculator.css (styles)"]:::frontend

            subgraph LIBS["Client-side Libraries"]
                L_MATH["Math.js (local compute engine)"]:::lib
                L_MJ["MathJax (typesetting)"]:::lib
                L_CHART["Chart.js (graph renderer)"]:::lib
                L_PDF["jsPDF (PDF export)"]:::lib
            end
        end
    end

    subgraph HOST["Static Hosting (Dev: Live Server / Prod: Any static host)"]
        STATIC["Serves static files (HTML/CSS/JS)"]:::infra
    end

    subgraph SRV["Server Runtime"]
        BE["Backend API (Node.js + Express)"]:::backend
        BE_SRV["server.js (Express app + routes)"]:::backend
        BE_PKG["package.json (deps/scripts)"]:::backend
        BE_LOCK["package-lock.json (lockfile)"]:::backend
        ENV[".env (GEMINI_API_KEY, PORT)"]:::secret
        MID["Middleware: CORS + dotenv"]:::backend
        HTTPCLIENT["HTTP client: node-fetch"]:::backend
    end

    subgraph EXT["External Service (Internet / 3rd-party)"]
        GEM["Google Gemini API"]:::externalService
    end

    %% Container interactions
    U -->|"interacts"| B
    STATIC -->|"serves HTML/CSS/JS"| B

    B -->|"runs"| FE_HTML
    B -->|"runs"| FE_JS
    B -->|"applies"| FE_CSS

    FE_JS -->|"local_eval"| L_MATH
    FE_JS -->|"typeset_math"| L_MJ
    FE_JS -->|"render_graph"| L_CHART
    FE_JS -->|"export_pdf"| L_PDF

    %% AI solver path
    FE_JS -->|"HTTPS_JSON (CORS) /api/solve"| BE
    BE -->|"routes/handlers"| BE_SRV
    BE_SRV -->|"uses"| MID
    MID -->|"loads_secrets"| ENV
    BE_SRV -->|"calls"| HTTPCLIENT
    HTTPCLIENT -->|"HTTPS (prompt_request)"| GEM
    GEM -->|"HTTPS (model_response)"| HTTPCLIENT
    BE -->|"HTTPS_JSON (steps+explanation)"| FE_JS

    %% =========================
    %% Diagram 2: Feature/Data Flows
    %% =========================

    subgraph FLOWS["Feature/Data-Flow View"]
        subgraph F1["Flow 1: Basic/Scientific (Local-only)"]
            F1_IN["User inputs expression"]:::note
            F1_EVAL["calculator.js evaluates"]:::frontend
            F1_MATH["Math.js compute"]:::lib
            F1_OUT["UI shows result (optional MathJax)"]:::note
            F1_IN --> F1_EVAL -->|"local_eval"| F1_MATH --> F1_OUT
        end

        subgraph F2["Flow 2: Graphing (Local-only)"]
            F2_IN["User inputs function f(x)"]:::note
            F2_SAMPLE["calculator.js samples x→y"]:::frontend
            F2_MATH["Math.js eval per sample"]:::lib
            F2_RENDER["Chart.js renders graph"]:::lib
            F2_IN --> F2_SAMPLE -->|"compute_points"| F2_MATH -->|"series_data"| F2_RENDER
        end

        subgraph F3["Flow 3: AI Solver (Client → Backend → Gemini)"]
            F3_IN["User submits word problem"]:::note
            F3_REQ["calculator.js POST /api/solve"]:::frontend
            F3_BE["Express handler (server.js)"]:::backend
            F3_FETCH["node-fetch to Gemini"]:::backend
            F3_GEM["Google Gemini API"]:::externalService
            F3_RESP["JSON response: steps+explanation"]:::note
            F3_IN --> F3_REQ -->|"HTTPS_JSON (CORS)"| F3_BE --> F3_FETCH -->|"HTTPS prompt_request"| F3_GEM -->|"HTTPS model_response"| F3_FETCH --> F3_BE --> F3_RESP
        end

        subgraph F4["Flow 4: Export (Local-only)"]
            F4_IN["User clicks Export PDF"]:::note
            F4_GEN["calculator.js generates document"]:::frontend
            F4_PDF["jsPDF creates PDF"]:::lib
            F4_DL["Download to user machine"]:::note
            F4_IN --> F4_GEN -->|"render_to_pdf"| F4_PDF --> F4_DL
        end
    end

    %% Click events (from component_mapping)
    click FE_HTML "https://github.com/mahender-reddy85/advanced-calculator/blob/main/frontend/index.html"
    click FE_JS "https://github.com/mahender-reddy85/advanced-calculator/blob/main/frontend/calculator.js"
    click FE_CSS "https://github.com/mahender-reddy85/advanced-calculator/blob/main/frontend/calculator.css"
    click BE_SRV "https://github.com/mahender-reddy85/advanced-calculator/blob/main/backend/server.js"
    click BE_PKG "https://github.com/mahender-reddy85/advanced-calculator/blob/main/backend/package.json"
    click BE_LOCK "https://github.com/mahender-reddy85/advanced-calculator/blob/main/backend/package-lock.json"

    %% README mapping (documentation)
    RD["README (runtime notes / two-process setup)"]:::doc
    click RD "https://github.com/mahender-reddy85/advanced-calculator/blob/main/README.md"
    RD -.->|"documents"| STATIC
    RD -.->|"documents"| BE

    %% Styles (color coding)
    classDef frontend fill:#1f77b4,stroke:#0b3d66,color:#ffffff,stroke-width:1.5px
    classDef backend fill:#2c7fb8,stroke:#0b3d66,color:#ffffff,stroke-width:1.5px
    classDef client fill:#4ea3d8,stroke:#0b3d66,color:#ffffff,stroke-width:1.5px
    classDef lib fill:#f0a202,stroke:#9a5a00,color:#1b1b1b,stroke-width:1.5px
    classDef externalService fill:#d64541,stroke:#7a1f1c,color:#ffffff,stroke-width:1.5px
    classDef external fill:#6c757d,stroke:#343a40,color:#ffffff,stroke-width:1.5px
    classDef infra fill:#8d99ae,stroke:#2b2d42,color:#ffffff,stroke-width:1.5px
    classDef secret fill:#111827,stroke:#fbbf24,color:#ffffff,stroke-width:2px
    classDef note fill:#f8f9fa,stroke:#adb5bd,color:#111827,stroke-width:1px
    classDef doc fill:#7c3aed,stroke:#3b0764,color:#ffffff,stroke-width:1.5px
```
