# omar-khecharem/scriptvaultocr architecture

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

- Interactive diagram: https://gitdiagram.com/omar-khecharem/scriptvaultocr
- Repository: https://github.com/omar-khecharem/scriptvaultocr

## Overview

ScriptVault OCR is a local web application for extracting and reviewing examination-form fields from images. The main workflow is browser upload → FastAPI OCR endpoint → image decoding and OCR → form extraction and validation, with optional visual-model assistance → structured results for manual review. The repository also exposes batch, form, health, and document-export capabilities. The README documents the principal OCR stages; source excerpts and the source index support the internal call links. Some unsampled implementation details and wiring are intentionally not inferred.

Main entry points: [`backend/api/app.py`](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/api/app.py) (FastAPI app), [`web/src/App.jsx`](https://github.com/omar-khecharem/scriptvaultocr/blob/main/web/src/App.jsx) (Review workspace), [`backend/application/use_cases/ocr_single.py`](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/application/use_cases/ocr_single.py) (Single-file OCR), [`backend/exam_ocr/core_ocr.py`](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/exam_ocr/core_ocr.py) (OCR engines)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Review interface"]
  node_appui["Review workspace<br/>[App.jsx]"]
  node_client["API client<br/>[client.js]"]
  node_review["Field review<br/>[FormPanel.jsx]"]
  node_canvas["Page viewer<br/>[ImageCanvas.jsx]"]
  node_batchview["Batch table<br/>[BatchTable.jsx]"]
  node_reviewlogic["Review helpers<br/>[review.js]"]
end

subgraph group_api["HTTP application"]
  node_apiapp["FastAPI app<br/>[app.py]"]
  node_ocrroute["OCR routes<br/>[ocr.py]"]
  node_batchroute["Batch routes<br/>[batch.py]"]
  node_formroute["Form routes<br/>[form.py]"]
  node_exportroute["Export routes<br/>[export.py]"]
  node_healthroute["Health route<br/>[health.py]"]
end

subgraph group_ocr["OCR and extraction"]
  node_single["Single-file OCR<br/>[ocr_single.py]"]
  node_batch["Batch processing<br/>[ocr_batch.py]"]
  node_engine["OCR engines<br/>[core_ocr.py]"]
  node_paddle["Paddle fallback<br/>[paddle_engine.py]"]
  node_preprocess["Image processing"]
  node_forms["Form analysis<br/>[form_analyzer.py]"]
  node_correction["Character correction<br/>[char_corrector.py]"]
  node_htr["Handwriting reader<br/>[htr_engine.py]"]
end

subgraph group_ai["AI and export"]
  node_vlmreader["Visual form reader<br/>[reader.py]"]
  node_providers["VLM providers<br/>[providers.py]"]
  node_vlmconfig["VLM configuration<br/>[vlm_config.py]"]
  node_export["Document export<br/>[document.py]"]
end

node_user(("Reviewer"))
node_ollama{{"Ollama"}}
node_cloudflare{{"Cloudflare AI"}}

node_user -->|"reviews"| node_appui
node_appui -->|"uploads files"| node_client
node_appui -->|"renders fields"| node_review
node_appui -->|"renders pages"| node_canvas
node_appui -->|"renders batches"| node_batchview
node_review -->|"uses review rules"| node_reviewlogic
node_client -->|"sends OCR request"| node_ocrroute
node_apiapp -->|"registers routes"| node_ocrroute
node_apiapp -->|"registers routes"| node_batchroute
node_apiapp -->|"registers routes"| node_formroute
node_apiapp -->|"registers routes"| node_exportroute
node_apiapp -->|"registers routes"| node_healthroute
node_ocrroute -->|"dispatches OCR"| node_single
node_batchroute -->|"processes files"| node_single
node_single -->|"recognizes images"| node_engine
node_single -->|"extracts fields"| node_forms
node_single -.->|"requests optional reading"| node_vlmreader
node_engine -->|"uses processing"| node_preprocess
node_engine -->|"uses HTR"| node_htr
node_engine -.->|"selects fallback"| node_paddle
node_paddle -->|"optionally reads handwriting"| node_htr
node_forms -->|"corrects characters"| node_correction
node_vlmreader -->|"creates provider"| node_providers
node_vlmreader -->|"uses settings"| node_vlmconfig
node_providers -.->|"calls selected service"| node_ollama
node_providers -.->|"calls selected service"| node_cloudflare
node_exportroute -->|"exports document"| node_export
node_batchroute -->|"dispatches batches"| node_batch

click node_appui "https://github.com/omar-khecharem/scriptvaultocr/blob/main/web/src/App.jsx"
click node_client "https://github.com/omar-khecharem/scriptvaultocr/blob/main/web/src/api/client.js"
click node_review "https://github.com/omar-khecharem/scriptvaultocr/blob/main/web/src/components/FormPanel.jsx"
click node_canvas "https://github.com/omar-khecharem/scriptvaultocr/blob/main/web/src/components/ImageCanvas.jsx"
click node_batchview "https://github.com/omar-khecharem/scriptvaultocr/blob/main/web/src/components/BatchTable.jsx"
click node_reviewlogic "https://github.com/omar-khecharem/scriptvaultocr/blob/main/web/src/utils/review.js"
click node_apiapp "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/api/app.py"
click node_ocrroute "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/api/routes/ocr.py"
click node_batchroute "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/api/routes/batch.py"
click node_formroute "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/api/routes/form.py"
click node_exportroute "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/api/routes/export.py"
click node_healthroute "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/api/routes/health.py"
click node_single "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/application/use_cases/ocr_single.py"
click node_batch "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/application/use_cases/ocr_batch.py"
click node_engine "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/exam_ocr/core_ocr.py"
click node_paddle "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/exam_ocr/paddle_engine.py"
click node_preprocess "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/exam_ocr/image_processing.py"
click node_forms "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/exam_ocr/form_analyzer.py"
click node_correction "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/exam_ocr/char_corrector.py"
click node_htr "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/exam_ocr/htr_engine.py"
click node_vlmreader "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/infrastructure/vlm/reader.py"
click node_providers "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/infrastructure/vlm/providers.py"
click node_vlmconfig "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/config/vlm_config.py"
click node_export "https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/infrastructure/exporter/document.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_appui,node_client,node_review,node_canvas,node_batchview,node_reviewlogic,node_user toneBlue
class node_apiapp,node_ocrroute,node_batchroute,node_formroute,node_exportroute,node_healthroute toneAmber
class node_single,node_batch,node_engine,node_paddle,node_preprocess,node_forms,node_correction,node_htr toneMint
class node_vlmreader,node_providers,node_vlmconfig,node_export toneRose
class node_ollama,node_cloudflare toneIndigo
```

## Components

### Review interface

- [Review workspace](https://github.com/omar-khecharem/scriptvaultocr/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [API client](https://github.com/omar-khecharem/scriptvaultocr/blob/main/web/src/api/client.js): `web/src/api/client.js`
- [Field review](https://github.com/omar-khecharem/scriptvaultocr/blob/main/web/src/components/FormPanel.jsx): `web/src/components/FormPanel.jsx`
- [Page viewer](https://github.com/omar-khecharem/scriptvaultocr/blob/main/web/src/components/ImageCanvas.jsx): `web/src/components/ImageCanvas.jsx`
- [Batch table](https://github.com/omar-khecharem/scriptvaultocr/blob/main/web/src/components/BatchTable.jsx): `web/src/components/BatchTable.jsx`
- [Review helpers](https://github.com/omar-khecharem/scriptvaultocr/blob/main/web/src/utils/review.js): `web/src/utils/review.js`

### HTTP application

- [FastAPI app](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/api/app.py): `backend/api/app.py`
- [OCR routes](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/api/routes/ocr.py): `backend/api/routes/ocr.py`
- [Batch routes](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/api/routes/batch.py): `backend/api/routes/batch.py`
- [Form routes](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/api/routes/form.py): `backend/api/routes/form.py`
- [Export routes](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/api/routes/export.py): `backend/api/routes/export.py`
- [Health route](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/api/routes/health.py): `backend/api/routes/health.py`

### OCR and extraction

- [Single-file OCR](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/application/use_cases/ocr_single.py): `backend/application/use_cases/ocr_single.py`
- [Batch processing](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/application/use_cases/ocr_batch.py): `backend/application/use_cases/ocr_batch.py`
- [OCR engines](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/exam_ocr/core_ocr.py): `backend/exam_ocr/core_ocr.py`
- [Paddle fallback](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/exam_ocr/paddle_engine.py): `backend/exam_ocr/paddle_engine.py`
- [Image processing](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/exam_ocr/image_processing.py): `backend/exam_ocr/image_processing.py`
- [Form analysis](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/exam_ocr/form_analyzer.py): `backend/exam_ocr/form_analyzer.py`
- [Character correction](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/exam_ocr/char_corrector.py): `backend/exam_ocr/char_corrector.py`
- [Handwriting reader](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/exam_ocr/htr_engine.py): `backend/exam_ocr/htr_engine.py`

### AI and export

- [Visual form reader](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/infrastructure/vlm/reader.py): `backend/infrastructure/vlm/reader.py`
- [VLM providers](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/infrastructure/vlm/providers.py): `backend/infrastructure/vlm/providers.py`
- [VLM configuration](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/config/vlm_config.py): `backend/config/vlm_config.py`
- [Document export](https://github.com/omar-khecharem/scriptvaultocr/blob/main/backend/infrastructure/exporter/document.py): `backend/infrastructure/exporter/document.py`

### Other components

- **Reviewer**
- **Ollama**
- **Cloudflare AI**

## Connections

- Reviewer → Review workspace: reviews (evidence: `README.md`)
- Review workspace → API client: uploads files (evidence: `web/src/App.jsx`)
- Review workspace → Field review: renders fields (evidence: `web/src/App.jsx`)
- Review workspace → Page viewer: renders pages (evidence: `web/src/App.jsx`)
- Review workspace → Batch table: renders batches (evidence: `web/src/App.jsx`)
- Field review → Review helpers: uses review rules
- API client → OCR routes: sends OCR request (evidence: `README.md`)
- FastAPI app → OCR routes: registers routes (evidence: `backend/api/app.py`)
- FastAPI app → Batch routes: registers routes (evidence: `backend/api/app.py`)
- FastAPI app → Form routes: registers routes (evidence: `backend/api/app.py`)
- FastAPI app → Export routes: registers routes (evidence: `backend/api/app.py`)
- FastAPI app → Health route: registers routes (evidence: `backend/api/app.py`)
- OCR routes → Single-file OCR: dispatches OCR
- Batch routes → Single-file OCR: processes files (evidence: `backend/api/routes/batch.py`)
- Single-file OCR → OCR engines: recognizes images (evidence: `backend/application/use_cases/ocr_single.py`)
- Single-file OCR → Form analysis: extracts fields (evidence: `backend/application/use_cases/ocr_single.py`)
- Single-file OCR → Visual form reader: requests optional reading (evidence: `backend/application/use_cases/ocr_single.py`)
- OCR engines → Image processing: uses processing (evidence: `backend/exam_ocr/core_ocr.py`)
- OCR engines → Handwriting reader: uses HTR (evidence: `backend/exam_ocr/core_ocr.py`)
- OCR engines → Paddle fallback: selects fallback (evidence: `README.md`)
- Paddle fallback → Handwriting reader: optionally reads handwriting (evidence: `backend/exam_ocr/paddle_engine.py`)
- Form analysis → Character correction: corrects characters (evidence: `backend/exam_ocr/form_analyzer.py`)
- Visual form reader → VLM providers: creates provider (evidence: `backend/infrastructure/vlm/reader.py`)
- Visual form reader → VLM configuration: uses settings (evidence: `backend/infrastructure/vlm/reader.py`)
- VLM providers → Ollama: calls selected service (evidence: `README.md`)
- VLM providers → Cloudflare AI: calls selected service (evidence: `README.md`)
- Export routes → Document export: exports document
- Batch routes → Batch processing: dispatches batches
