# samar7q/handwritten_images_to_word_docx architecture

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

- Interactive diagram: https://gitdiagram.com/samar7q/handwritten_images_to_word_docx
- Repository: https://github.com/samar7q/handwritten_images_to_word_docx

## Overview

This product turns uploaded or command-line handwritten notes into downloadable, editable Word documents. The main workflow preprocesses an image, optionally detects and masks diagrams, runs OCR with selectable or fallback engines, corrects and structures the extracted text, then generates a Word file with diagrams embedded. The web UI also exposes model selection, progress, previews, and OCR metrics. The graph reflects the documented workflow and sampled call sites; unsampled implementation details and uncertain internal wiring are omitted.

Main entry points: [`app.py`](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/app.py) (Streamlit UI), [`src/ocr/hybrid_ocr.py`](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/ocr/hybrid_ocr.py) (Hybrid OCR), [`src/main_pipeline.py`](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/main_pipeline.py) (Pipeline Orchestrator), [`src/preprocessing/diagram_detector.py`](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/preprocessing/diagram_detector.py) (Diagram Detector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interfaces"]
  node_web["Streamlit UI<br/>[app.py]"]
  node_cli["CLI Entry<br/>[main_pipeline.py]"]
  node_download["Download Result<br/>[app.py]"]
end

subgraph group_workflow["Conversion Workflow"]
  node_pipeline["Pipeline Orchestrator<br/>[main_pipeline.py]"]
  node_preprocess["Image Preprocessor<br/>[image_processor.py]"]
  node_diagrams["Diagram Detector"]
end

subgraph group_recognition["OCR Engines"]
  node_hybrid["Hybrid OCR<br/>[hybrid_ocr.py]"]
  node_vision["Vision OCR<br/>[vision_ocr.py]"]
  node_florence["Florence OCR"]
  node_got["GOT-OCR<br/>[got_ocr_local.py]"]
  node_easy["EasyOCR Fallback<br/>[hybrid_ocr.py]"]
end

subgraph group_outputs["Correction and Output"]
  node_corrector["LLM Corrector<br/>[llm_corrector.py]"]
  node_word["Word Generator<br/>[word_generator.py]"]
end

node_user(("Notes User"))
node_image["Input Image"]
node_groq{{"Groq API"}}
node_doc["Word Document"]

node_user -->|"uploads image"| node_web
node_user -->|"provides image"| node_cli
node_cli -->|"starts conversion"| node_pipeline
node_web -->|"preprocesses image"| node_preprocess
node_web -->|"detects diagrams"| node_diagrams
node_web -->|"selects OCR"| node_hybrid
node_web -->|"requests correction"| node_corrector
node_web -->|"creates document"| node_word
node_pipeline -->|"preprocesses image"| node_preprocess
node_pipeline -->|"detects diagrams"| node_diagrams
node_pipeline -->|"extracts text"| node_hybrid
node_pipeline -->|"corrects text"| node_corrector
node_pipeline -->|"generates document"| node_word
node_image -->|"image data"| node_preprocess
node_diagrams -->|"text-only image"| node_hybrid
node_diagrams -->|"diagram images"| node_word
node_hybrid -->|"tries API OCR"| node_vision
node_hybrid -->|"falls back"| node_florence
node_hybrid -->|"falls back"| node_got
node_hybrid -->|"final fallback"| node_easy
node_vision -->|"sends image"| node_groq
node_corrector -->|"requests correction"| node_groq
node_word -->|"saves document"| node_doc
node_web -->|"offers download"| node_download
node_download -->|"reads file"| node_doc

click node_web "https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/app.py"
click node_cli "https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/main_pipeline.py"
click node_pipeline "https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/main_pipeline.py"
click node_preprocess "https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/preprocessing/image_processor.py"
click node_diagrams "https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/preprocessing/diagram_detector.py"
click node_hybrid "https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/ocr/hybrid_ocr.py"
click node_vision "https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/ocr/vision_ocr.py"
click node_florence "https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/ocr/florence_local_ocr.py"
click node_got "https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/ocr/got_ocr_local.py"
click node_easy "https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/ocr/hybrid_ocr.py"
click node_corrector "https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/postprocessing/llm_corrector.py"
click node_word "https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/document_generation/word_generator.py"
click node_download "https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/app.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_web,node_cli,node_download,node_user toneBlue
class node_pipeline,node_preprocess,node_diagrams toneAmber
class node_hybrid,node_vision,node_florence,node_got,node_easy,node_groq toneMint
class node_corrector,node_word toneRose
class node_image,node_doc toneIndigo
```

## Components

### User Interfaces

- [Streamlit UI](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/app.py): `app.py`
- [CLI Entry](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/main_pipeline.py): `src/main_pipeline.py`
- [Download Result](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/app.py): `app.py`

### Conversion Workflow

- [Pipeline Orchestrator](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/main_pipeline.py): `src/main_pipeline.py`
- [Image Preprocessor](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/preprocessing/image_processor.py): `src/preprocessing/image_processor.py`
- [Diagram Detector](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/preprocessing/diagram_detector.py): `src/preprocessing/diagram_detector.py`

### OCR Engines

- [Hybrid OCR](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/ocr/hybrid_ocr.py): `src/ocr/hybrid_ocr.py`
- [Vision OCR](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/ocr/vision_ocr.py): `src/ocr/vision_ocr.py`
- [Florence OCR](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/ocr/florence_local_ocr.py): `src/ocr/florence_local_ocr.py`
- [GOT-OCR](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/ocr/got_ocr_local.py): `src/ocr/got_ocr_local.py`
- [EasyOCR Fallback](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/ocr/hybrid_ocr.py): `src/ocr/hybrid_ocr.py`

### Correction and Output

- [LLM Corrector](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/postprocessing/llm_corrector.py): `src/postprocessing/llm_corrector.py`
- [Word Generator](https://github.com/samar7q/handwritten_images_to_word_docx/blob/main/src/document_generation/word_generator.py): `src/document_generation/word_generator.py`

### Other components

- **Notes User**
- **Input Image**
- **Groq API**
- **Word Document**

## Connections

- Notes User → Streamlit UI: uploads image
- Notes User → CLI Entry: provides image
- CLI Entry → Pipeline Orchestrator: starts conversion
- Streamlit UI → Image Preprocessor: preprocesses image
- Streamlit UI → Diagram Detector: detects diagrams
- Streamlit UI → Hybrid OCR: selects OCR
- Streamlit UI → LLM Corrector: requests correction
- Streamlit UI → Word Generator: creates document
- Pipeline Orchestrator → Image Preprocessor: preprocesses image
- Pipeline Orchestrator → Diagram Detector: detects diagrams
- Pipeline Orchestrator → Hybrid OCR: extracts text
- Pipeline Orchestrator → LLM Corrector: corrects text
- Pipeline Orchestrator → Word Generator: generates document
- Input Image → Image Preprocessor: image data
- Diagram Detector → Hybrid OCR: text-only image
- Diagram Detector → Word Generator: diagram images
- Hybrid OCR → Vision OCR: tries API OCR
- Hybrid OCR → Florence OCR: falls back
- Hybrid OCR → GOT-OCR: falls back
- Hybrid OCR → EasyOCR Fallback: final fallback
- Vision OCR → Groq API: sends image
- LLM Corrector → Groq API: requests correction
- Word Generator → Word Document: saves document
- Streamlit UI → Download Result: offers download
- Download Result → Word Document: reads file