# mahender-reddy85/docuquery architecture

> Architecture diagram of the GitHub repository mahender-reddy85/docuquery, 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/docuquery
- Repository: https://github.com/mahender-reddy85/docuquery

## Overview

##### Project type & purpose (what you’re diagramming)
DocuQuery is a **small full-stack web application** with a **privacy-first architecture**:

- **Frontend (static HTML/CSS/vanilla JS)** runs in the browser and does:
- File upload (PDF/DOCX/TXT)
- **Client-side text extraction** (PDF.js, Mammoth.js, TXT parsing)
- Chat UI + session state (chat history, theme preference)
- Calls backend only to generate AI responses
- **Backend (Node/Express proxy)** exists primarily to:
- Hide the **Gemini API key** in server-side env (`GEMINI_API_KEY`)
- Forward requests to **Google Gemini** (`gemini-2.0-flash`) via `POST /api/generate`

That means the “system” is intentionally simple: **Browser does the heavy lifting; server is a thin credentialed proxy.**

##### File tree analysis (map code to components)
Actual repository tree indicates a split app:

**Frontend**
- `frontend/index.html` – UI structure: upload screen + Q&A screen
- `frontend/DocuQuery.js` – main client logic:
- drag/drop + file picker
- text extraction pipeline per file type
- prompt construction (document grounding)
- fetch to backend `/api/generate`
- theme toggle + localStorage
- `frontend/DocuQuery.css` – responsive + dark mode styling

**Backend**
- `backend/server.js` – Express server exposing `POST /api/generate`
- `backend/package.json` / lock – backend dependencies/scripts

**Top-level**
- `README.md` – explains “client-side processing” + proxy server pattern

This strongly suggests a **2-tier architecture** with an external AI dependency.

##### Client (Browser) — primary compute + data handling
Subcomponents worth drawing separately (because they matter to privacy/flow):
##### Upload & File Handler
- Drag & drop, file picker
- Accepts PDF/DOCX/TXT (PPTX shown but not implemented)
##### Text Extraction Layer (in-browser)
- PDF.js → extracted text
- Mammoth.js → extracted text
- TXT → raw text
##### Document Text Store (in-memory)
- Extracted text kept in browser memory (not persisted server-side)
##### Chat / Prompt Builder
- Builds “grounded” request using extracted document text + user question
- Maintains chat history for the session
##### UI & Theme Manager
- Light/dark mode, responsive layout
- localStorage only for theme preference (not documents)

##### Backend (Node/Express) — security boundary + proxy
Subcomponents to show:
##### Express API
- `POST /api/generate`
##### Environment / Secrets
- `GEMINI_API_KEY` from `.env`/env var
##### Request Forwarder
- Calls Gemini endpoint and returns response
##### (Implicit) CORS / HTTP boundary
- Browser → localhost:3000

##### Google Gemini API
- Model: `gemini-2.0-flash`
- Receives prompt (document text + question) and returns generated answer

##### User → Browser UI
- Upload document
##### Browser → Text Extraction
- PDF.js/Mammoth.js parse locally
##### Browser stores extracted text
- “Document Text (in-memory)”
##### User → Browser Chat input
- Ask a question
##### Browser Prompt Builder
- Combines question + extracted text into a grounded request
##### Browser → Backend
- `POST /api/generate` (payload includes document text and question, plus settings like temperature if present)
##### Backend → Gemini API
- Adds API key server-side
- Forwards request
##### Gemini API → Backend → Browser
- Response returned to UI chat panel

- **Document extraction stays in the browser**
- **No persistent storage** (no DB)
- **API key never goes to the browser**

##### Thin Backend / Backend-for-Frontend (BFF) Proxy
- Backend exists to protect secrets and normalize API calls
##### Client-side processing
- Compute-heavy extraction is local
##### External AI dependency
- Gemini is a runtime dependency; model name is part of architecture
##### No database / stateless server
- The server can be drawn stateless (horizontal scaling possible)
##### Trust boundaries
- Browser is untrusted for secrets; backend is trusted for key storage

##### “Don’t overthink it”: maximize components without inventing things
Given the repo size, the most common diagramming mistake is adding infrastructure that isn’t present (queues, vector DBs, object storage, auth). This project currently has:
- static frontend files
- one Node server
- one external API

So be detailed by **splitting real responsibilities** (upload, extraction, prompt building, proxying), not by adding imaginary services.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1: System Context (L1)
  %% =========================
  subgraph "Diagram 1 — System Context (C4 L1)"
    direction TB

    U["User"]:::external

    subgraph "Browser (DocuQuery Frontend)"
      direction TB
      FE1["Static Frontend App\n(frontend/index.html + frontend/DocuQuery.js + frontend/DocuQuery.css)"]:::client
      NOTE1["Note: Text extraction happens in the browser\nNo DB / no persistent storage"]:::note
    end

    subgraph "Node/Express Proxy (DocuQuery Backend)"
      direction TB
      BE1["backend/server.js\nExpress API: POST /api/generate"]:::backend
      NOTE2["Note: GEMINI_API_KEY stored server-side only\n(thin BFF proxy; stateless)"]:::note
    end

    GEM["Google Gemini API\nModel: gemini-2.0-flash"]:::externalSvc

    U -->|"uploads_file + asks_question"| FE1
    FE1 -->|"POST /api/generate\n(question + document_text)"| BE1
    BE1 -->|"forwards_request + adds_API_key"| GEM
    GEM -->|"generated_answer"| BE1
    BE1 -->|"answer_json"| FE1
    FE1 -->|"renders_answer"| U

    TB1["Trust boundary:\nBrowser is untrusted for secrets"]:::trust
    FE1 -.->|"no_API_key_leak"| TB1
    TB1 -.-> BE1
  end

  %% =========================
  %% Diagram 2: Container / Component View (L2-L3 hybrid)
  %% =========================
  subgraph "Diagram 2 — Container/Component View (C4 L2-L3 hybrid)"
    direction TB

    U2["User"]:::external

    subgraph "Browser (DocuQuery Frontend Runtime)"
      direction TB

      subgraph "UI Layer"
        direction TB
        UIHTML["UI Structure\nUpload screen + Q&A screen\n(frontend/index.html)"]:::client
        CHATUI["Chat UI + Session State\n(chat_history in-session)"]:::client
        THEME["Theme Manager\n(light/dark)\nlocalStorage: theme only"]:::client
        CSS["Styling / Responsive Layout\n(frontend/DocuQuery.css)"]:::client
      end

      subgraph "Client Logic (frontend/DocuQuery.js)"
        direction TB
        MAINJS["DocuQuery Client Controller\n(frontend/DocuQuery.js)"]:::client
        UPLOAD["Upload & File Handler\n(drag/drop + file picker)\nPDF/DOCX/TXT\n(PPTX shown, not implemented)"]:::client

        subgraph "Text Extraction Layer (in-browser)"
          direction TB
          PDFJS["PDF Extractor\n(PDF.js)"]:::clientLib
          MAMMOTH["DOCX Extractor\n(Mammoth.js)"]:::clientLib
          TXTP["TXT Parser\n(raw text)"]:::clientLib
        end

        DOCSTORE["Document Text Store\n(in-memory only)"]:::memory
        PROMPT["Prompt Builder / Grounding\n(question + extracted_text)\nmaintains chat context"]:::client
      end
    end

    subgraph "Backend (Node/Express Proxy)"
      direction TB
      SERVER["Express Server\nbackend/server.js"]:::backend
      ROUTE["Route: POST /api/generate"]:::backend
      ENV["Env/Secrets\nGEMINI_API_KEY\n(dotenv/env var)"]:::secret
      FWD["Gemini Request Forwarder\nHTTP client -> Gemini\nreturns response"]:::backend
      PKG["Backend deps/scripts\n(backend/package.json)"]:::backendMeta
      LOCK["Lockfile\n(backend/package-lock.json)"]:::backendMeta
      NOTE3["Stateless proxy\nNo DB / no server persistence"]:::note
    end

    GEM2["Google Gemini API\nModel: gemini-2.0-flash"]:::externalSvc
    DOCS["Project Documentation\n(README.md)\nprivacy-first + client-side processing + proxy pattern"]:::doc

    %% User interactions
    U2 -->|"selects_or_drops_file"| UPLOAD
    U2 -->|"asks_question"| CHATUI

    %% Frontend internal flow
    UIHTML --> MAINJS
    UPLOAD -->|"routes_by_file_type"| MAINJS
    MAINJS -->|"PDF"| PDFJS
    MAINJS -->|"DOCX"| MAMMOTH
    MAINJS -->|"TXT"| TXTP

    PDFJS -->|"extracted_text"| DOCSTORE
    MAMMOTH -->|"extracted_text"| DOCSTORE
    TXTP -->|"raw_text"| DOCSTORE

    DOCSTORE -->|"document_text"| PROMPT
    CHATUI -->|"user_question + chat_history"| PROMPT
    THEME -->|"reads/writes theme_pref"| MAINJS
    CSS --> UIHTML

    PROMPT -->|"grounded_prompt\n(question + document_text)"| ROUTE

    %% Backend internal flow
    SERVER --> ROUTE
    ENV -->|"API_key(server-side_only)"| FWD
    ROUTE -->|"request_body(prompt)"| FWD
    FWD -->|"calls"| GEM2
    GEM2 -->|"answer"| FWD
    FWD -->|"response_json"| ROUTE
    ROUTE -->|"answer_json"| CHATUI

    %% Trust boundary emphasis
    TB2["Trust boundary:\nNo secrets in browser\nDoc extraction is client-side\nBut doc text is sent to backend+Gemini for Q&A"]:::trust
    PROMPT -.-> TB2
    TB2 -.-> ROUTE

    %% Documentation linkage (non-runtime)
    DOCS -.->|"describes_architecture"| UIHTML
    DOCS -.->|"describes_proxy_pattern"| SERVER
  end

  %% =========================
  %% Click events (component mapping)
  %% =========================
  click UIHTML "https://github.com/mahender-reddy85/docuquery/blob/main/frontend/index.html"
  click MAINJS "https://github.com/mahender-reddy85/docuquery/blob/main/frontend/DocuQuery.js"
  click CSS "https://github.com/mahender-reddy85/docuquery/blob/main/frontend/DocuQuery.css"
  click SERVER "https://github.com/mahender-reddy85/docuquery/blob/main/backend/server.js"
  click ROUTE "https://github.com/mahender-reddy85/docuquery/blob/main/backend/server.js"
  click ENV "https://github.com/mahender-reddy85/docuquery/blob/main/backend/server.js"
  click FWD "https://github.com/mahender-reddy85/docuquery/blob/main/backend/server.js"
  click PKG "https://github.com/mahender-reddy85/docuquery/blob/main/backend/package.json"
  click LOCK "https://github.com/mahender-reddy85/docuquery/blob/main/backend/package-lock.json"
  click DOCS "https://github.com/mahender-reddy85/docuquery/blob/main/README.md"
  click FE1 "https://github.com/mahender-reddy85/docuquery/blob/main/frontend/index.html"
  click BE1 "https://github.com/mahender-reddy85/docuquery/blob/main/backend/server.js"

  %% =========================
  %% Styles
  %% =========================
  classDef client fill:#1e88e5,stroke:#0d47a1,color:#ffffff,stroke-width:1.5px
  classDef clientLib fill:#42a5f5,stroke:#0d47a1,color:#ffffff,stroke-width:1.2px
  classDef backend fill:#2e7d32,stroke:#1b5e20,color:#ffffff,stroke-width:1.5px
  classDef backendMeta fill:#66bb6a,stroke:#1b5e20,color:#0b2e10,stroke-width:1.2px
  classDef externalSvc fill:#fb8c00,stroke:#e65100,color:#1f1300,stroke-width:1.5px
  classDef external fill:#8e24aa,stroke:#4a148c,color:#ffffff,stroke-width:1.5px
  classDef secret fill:#c62828,stroke:#7f0000,color:#ffffff,stroke-width:1.7px
  classDef memory fill:#1565c0,stroke:#0d47a1,color:#ffffff,stroke-dasharray: 4 3,stroke-width:1.5px
  classDef note fill:#fff3e0,stroke:#ef6c00,color:#4e342e,stroke-width:1px
  classDef trust fill:#ffebee,stroke:#c62828,color:#3e2723,stroke-width:1.6px,stroke-dasharray: 6 4
  classDef doc fill:#f3e5f5,stroke:#6a1b9a,color:#311b3f,stroke-width:1.2px
```
