# gauravm512/docuflex architecture

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

- Interactive diagram: https://gitdiagram.com/gauravm512/docuflex
- Repository: https://github.com/gauravm512/docuflex

## Overview

##### Read the file tree as architecture signals
Top-level cues from the tree:
- `main.py` → app bootstrap; includes FastAPI instance, mounts static, includes routers, template engine setup
- `routes/` → **API/controller layer** (FastAPI routers): `convert.py`, `pdf_utils.py`, `ocr.py`, `qr.py`
- `services/` → **business logic layer**: `convert_service.py`, `pdf_service.py`, `ocr_service.py`, plus `file_utils.py` for validation/storage/cleanup
- `templates/` + `static/` → server-rendered UI + JS-enhanced upload/download behavior
- `routes/pdf_utils.py` and `services/pdf_service.py` indicate PDF ops are separated from “conversion”
- `routes/qr.py` exists but README says QR is frontend-only at `/qr` → route likely serves the page; generation logic is in `static/app.js` or template JS
- `requirements.txt` / `pyproject.toml` → Python packaging + dependencies (PyMuPDF, Pillow, pdf2docx, pytesseract)

This structure strongly suggests a clean **3-layer separation**:
**UI (templates/static) → Routes (FastAPI routers) → Services (processing + file utils)**

##### Use the README to anchor “truth”
- “**Stateless** processing” (no DB)
- “**Temporary local storage** during processing” (uploads/outputs) then delete
- “**Client submits files using HTML/JS**”
- “**Service layer** performs processing using PyMuPDF, Pillow, OCR”
- “**Output returned as download response**”
- “**QR codes generated directly in the browser using JavaScript**”
- Security: size limits, type validation, UUID filenames, auto-cleanup

##### Browser POST `/ocr/pdf` with UploadFile
2. `routes/ocr.py` → `file_utils.validate()` + `file_utils.save_upload()` → writes to `uploads/uuid.pdf`
##### `ocr_service.ocr_pdf()`
- uses PyMuPDF to render pages → temp images
- calls pytesseract/Tesseract per page → aggregated text
##### `file_utils.cleanup()` deletes temp input/output

**Flow example: PDF Merge**
##### Return output → cleanup

**Flow example: QR generation**
##### Browser JS generates QR locally (no backend processing)

These flows make the “no DB, ephemeral filesystem” design unmissable.

##### Main components to include (separate into as many as possible)
- **Browser UI**
- HTML pages (templates)
- JS upload/download logic (`static/app.js`)
- QR generator (client-side)
- **FastAPI Application**
- Router: Convert
- Router: PDF Utils
- Router: OCR
- Router: QR page
- **Service modules**
- Convert Service
- PDF Service
- OCR Service
- File Utils (validation + storage + cleanup) *(this is a key shared component)*
- **Temp Storage**
- uploads/
- outputs/
- **External/native dependencies**
- Tesseract OCR binary

- **Browser → FastAPI**: `GET /` pages, `POST /convert/*` uploads, `POST /pdf/*`, `POST /ocr/*`
- **FastAPI Routes → file_utils**: validate type/size, generate UUID filename, save/delete
- **Routes → Services**: invoke processing functions
- **Services → Temp Storage**: read input, write output
- **OCR Service → Tesseract**: OCR invocation
- **FastAPI → Browser**: download response (FileResponse/StreamingResponse)

- validation failure → HTTP 400/415
- size limit exceeded → HTTP 413
- OCR engine missing → HTTP 500 with message (or explicit “dependency not installed”)

##### Architectural patterns/design principles to highlight (project-specific)
- **Stateless request processing** (no persistence, no sessions)
- **Layered architecture**: Routes/Controllers vs Services vs Utilities
- **Shared cross-cutting concern**: `file_utils` for security + cleanup
- **Privacy-by-design**: temp-only storage + deletion
- **Client-side feature isolation**: QR generation entirely in browser (reduced server load/security surface)

##### Diagramming conventions (make it principal-engineer grade)
Include:
- **Clear labels**: endpoint groups, modules, and responsibilities
- Blue: UI (Browser, templates, static)
- Green: FastAPI routes/controllers
- Orange: Services/business logic
- Purple: external dependencies (Tesseract)
- **Trust boundaries**:
- “Client machine” vs “Server runtime”
- Optionally “Container boundary” if Docker deployment is used

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Trust Boundaries
  %% =========================
  subgraph "Client Machine (Browser)"
    direction TB
    U["User"]:::external

    subgraph "Browser UI"
      direction TB
      B["Web Browser"]:::client
      JS["Client-side JS\n(uploads/downloads + QR generation)"]:::ui
      QRJS["QR Generator (100% client-side)"]:::ui
    end
  end

  subgraph "Server Runtime (DocuFlex - Stateless Monolith)"
    direction TB

    NOTE_STATELESS["Stateless Processing\n• No DB / No auth\n• No sessions\n• Ephemeral temp files only"]:::note
    NOTE_PRIVACY["Privacy-by-design\nTemp uploads/outputs deleted after response"]:::note

    subgraph "FastAPI Application"
      direction TB
      APP["FastAPI App Bootstrap\n(static mount + Jinja2 templates + router registration)"]:::app

      subgraph "Routes / Controllers (routes/*)"
        direction TB
        R_CONVERT["Convert Router\n/convert/*"]:::route
        R_PDF["PDF Utils Router\n/pdf/*"]:::route
        R_OCR["OCR Router\n/ocr/*"]:::route
        R_QR["QR Router\n/qr (serves UI page)"]:::route
      end

      subgraph "UI Rendering + Assets"
        direction TB
        TEMPL["Server-rendered Templates (Jinja2)\n/templates/*"]:::ui
        STATIC["Static Assets\n/static/*"]:::ui
      end
    end

    subgraph "Services / Business Logic (services/*)"
      direction TB
      FILEUTIL["File Utils\nvalidate + size/type checks\nUUID naming + temp save + cleanup"]:::util

      CONVSVC["Convert Service\n(PDF↔DOCX, image↔PDF, PDF→image)"]:::service
      PDFSVC["PDF Service\n(merge/split/reorder/compress)"]:::service
      OCRSVC["OCR Service\n(render pages + OCR aggregation)"]:::service
      QRSVC["QR Service (backend)\n(potential/legacy)"]:::service
    end

    subgraph "Ephemeral Local Storage (NOT a database)"
      direction TB
      FS[("Temp Filesystem\nuploads/ + outputs/")]:::storage
    end

    subgraph "External / Native Dependencies"
      direction TB
      TESS["Tesseract OCR Engine\n(native binary)"]:::external
      LIBS["Python Libraries\nPyMuPDF • Pillow • pdf2docx • pytesseract"]:::external
    end
  end

  %% =========================
  %% Main Request/Response Flows
  %% =========================
  U -->|"uses"| B

  %% Page loads
  B -->|"GET pages"| APP
  APP -->|"render HTML"| TEMPL
  APP -->|"serve /static"| STATIC
  STATIC -->|"JS/CSS"| B
  TEMPL -->|"HTML"| B

  %% Upload-based processing
  B -->|"POST /convert/*\n(file upload)"| R_CONVERT
  B -->|"POST /pdf/*\n(files upload)"| R_PDF
  B -->|"POST /ocr/*\n(file upload)"| R_OCR

  %% QR page (no backend processing)
  B -->|"GET /qr"| R_QR
  R_QR -->|"render qr.html"| TEMPL
  JS -->|"generates QR locally"| QRJS

  %% Controller -> utilities/services
  R_CONVERT -->|"validate+save_temp"| FILEUTIL
  R_PDF -->|"validate+save_temp"| FILEUTIL
  R_OCR -->|"validate+save_temp"| FILEUTIL

  R_CONVERT -->|"process"| CONVSVC
  R_PDF -->|"process"| PDFSVC
  R_OCR -->|"process"| OCRSVC

  %% Services -> filesystem
  FILEUTIL -->|"write/read temp"| FS
  CONVSVC -->|"read input\nwrite output"| FS
  PDFSVC -->|"read input\nwrite output"| FS
  OCRSVC -->|"render temp images\nwrite output"| FS

  %% OCR -> Tesseract
  OCRSVC -->|"invoke via pytesseract"| TESS

  %% Libraries used by services
  CONVSVC -.->|"uses"| LIBS
  PDFSVC -.->|"uses"| LIBS
  OCRSVC -.->|"uses"| LIBS

  %% Response + cleanup
  R_CONVERT -->|"return download\n(FileResponse/StreamingResponse)"| B
  R_PDF -->|"return download\n(FileResponse/StreamingResponse)"| B
  R_OCR -->|"return download\n(FileResponse/StreamingResponse)"| B

  R_CONVERT -->|"cleanup temp"| FILEUTIL
  R_PDF -->|"cleanup temp"| FILEUTIL
  R_OCR -->|"cleanup temp"| FILEUTIL
  FILEUTIL -->|"delete uploads/outputs"| FS

  %% Error paths (dotted)
  R_CONVERT -.->|"HTTP 400/415\n(validation fail)"| B
  R_PDF -.->|"HTTP 400/415\n(validation fail)"| B
  R_OCR -.->|"HTTP 400/415\n(validation fail)"| B
  R_CONVERT -.->|"HTTP 413\n(size limit)"| B
  R_PDF -.->|"HTTP 413\n(size limit)"| B
  R_OCR -.->|"HTTP 413\n(size limit)"| B
  OCRSVC -.->|"HTTP 500\n(Tesseract missing)"| R_OCR

  NOTE_STATELESS --- APP
  NOTE_PRIVACY --- FILEUTIL

  %% =========================
  %% Key Dataflow Examples (numbered)
  %% =========================
  subgraph "Key Flows (Data Lifecycle)"
    direction TB
    F1["Flow A: OCR PDF\n1) POST /ocr/pdf\n2) validate+save uploads/uuid.pdf\n3) render pages → OCR → aggregate\n4) write outputs/uuid.txt\n5) return download\n6) cleanup deletes temp"]:::note
    F2["Flow B: PDF Merge\n1) POST /pdf/merge (multi-file)\n2) validate+save temp\n3) merge via PDF service\n4) return merged PDF\n5) cleanup deletes temp"]:::note
    F3["Flow C: QR Generation\n1) GET /qr\n2) JS generates QR in-browser\n(no server processing)"]:::note
  end

  F1 --- R_OCR
  F2 --- R_PDF
  F3 --- R_QR

  %% =========================
  %% Click Events (component mapping)
  %% =========================
  click APP "https://github.com/gauravm512/docuflex/blob/master/main.py"
  click R_CONVERT "https://github.com/gauravm512/docuflex/blob/master/routes/convert.py"
  click R_PDF "https://github.com/gauravm512/docuflex/blob/master/routes/pdf_utils.py"
  click R_OCR "https://github.com/gauravm512/docuflex/blob/master/routes/ocr.py"
  click R_QR "https://github.com/gauravm512/docuflex/blob/master/routes/qr.py"
  click FILEUTIL "https://github.com/gauravm512/docuflex/blob/master/services/file_utils.py"
  click CONVSVC "https://github.com/gauravm512/docuflex/blob/master/services/convert_service.py"
  click PDFSVC "https://github.com/gauravm512/docuflex/blob/master/services/pdf_service.py"
  click OCRSVC "https://github.com/gauravm512/docuflex/blob/master/services/ocr_service.py"
  click QRSVC "https://github.com/gauravm512/docuflex/blob/master/services/qr_service.py"
  click TEMPL "https://github.com/gauravm512/docuflex/tree/master/templates/"
  click STATIC "https://github.com/gauravm512/docuflex/tree/master/static/"
  click JS "https://github.com/gauravm512/docuflex/blob/master/static/app.js"
  click NOTE_STATELESS "https://github.com/gauravm512/docuflex/blob/master/pyproject.toml"
  click NOTE_PRIVACY "https://github.com/gauravm512/docuflex/blob/master/requirements.txt"

  %% Template file click events (mapped)
  click TEMPL "https://github.com/gauravm512/docuflex/tree/master/templates/"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/base.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/index.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/convert.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/convert_pdf_to_word.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/convert_word_to_pdf.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/convert_image_to_pdf.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/convert_pdf_to_image.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/pdf.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/pdf_merge.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/pdf_split.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/pdf_reorder.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/pdf_compress.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/ocr.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/ocr_image.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/ocr_pdf.html"
  click TEMPL "https://github.com/gauravm512/docuflex/blob/master/templates/qr.html"
  click STATIC "https://github.com/gauravm512/docuflex/blob/master/static/styles.css"
  click STATIC "https://github.com/gauravm512/docuflex/blob/master/static/app.js"
  click STATIC "https://github.com/gauravm512/docuflex/tree/master/static/"

  %% Directory click events (mapped)
  click R_CONVERT "https://github.com/gauravm512/docuflex/tree/master/routes/"
  click CONVSVC "https://github.com/gauravm512/docuflex/tree/master/services/"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#7c3aed,stroke:#4c1d95,color:#ffffff,stroke-width:1.5px
  classDef client fill:#1d4ed8,stroke:#1e3a8a,color:#ffffff,stroke-width:1.5px
  classDef ui fill:#2563eb,stroke:#1e40af,color:#ffffff,stroke-width:1.5px
  classDef app fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:1.5px
  classDef route fill:#16a34a,stroke:#14532d,color:#ffffff,stroke-width:1.5px
  classDef service fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:1.5px
  classDef util fill:#f97316,stroke:#9a3412,color:#111827,stroke-width:1.5px
  classDef storage fill:#6b7280,stroke:#374151,color:#ffffff,stroke-width:1.5px
  classDef note fill:#fde68a,stroke:#b45309,color:#111827,stroke-width:1.5px
```
