# shiv1810/bill-scanner-ocr architecture

> Architecture diagram of the GitHub repository shiv1810/bill-scanner-ocr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shiv1810/bill-scanner-ocr
- Repository: https://github.com/shiv1810/bill-scanner-ocr

## Overview

##### Main Components Identification
- Frontend: Represented by the “frontend” directory with index.html, script.js, and styles.css. This part handles user interactions such as file uploads and displays results.
- Backend (Flask Application): The “backend/app.py” file acts as the core API server. Within this component, outline the following:
- API Endpoints: /upload-invoice, /confirm-invoice, and /debug-info.
- Image Preprocessing Pipeline: A sequential process including initial processing (upscaling, deskewing), enhancement (grayscale, CLAHE, thresholding), and document-specific operations (different handling for handwritten vs. printed documents).
- OCR Processing: Integration with Tesseract to convert processed images into text.
- PDF Processing: Integration with pdf2image to convert PDF invoices to images.
- Database: As described in the README, a MySQL database is used to store the extracted invoice data. Although not seen in the file tree, it is a crucial external component.
- Debug/Monitoring Modules: Note that the application generates and saves debug images and logs (even if the folder isn’t explicit in the file tree, mention that this functionality is built into the processing pipeline).

##### Relationships and Interactions
- The Frontend sends HTTP requests (via the API endpoints) to the Backend to upload invoices.
- The Backend processes the file by passing it sequentially through the preprocessing pipeline and then performs OCR.
- Once data is extracted, it may either be returned to the frontend (for confirmation) or saved into the MySQL database.
- There is data flow between the image processing modules and the OCR engine, with configuration differences based on the document style (printed vs. handwritten).
- Debug data flows out to log files and debug image folders to facilitate troubleshooting.

##### Architectural Patterns and Technologies
- MVC-like separation: Although a minimal project, the separation between frontend (view) and backend (controller/model) is clear.
- RESTful API design: The backend exposes endpoints for file upload, invoice confirmation, and debugging.
- Pipeline processing pattern: The image preprocessing uses a step-by-step pipeline to improve OCR accuracy.
- Technologies: Python with Flask for the server, OpenCV for image processing, Tesseract for OCR, pdf2image for handling PDFs, and MySQL as the persistence layer.

- “Frontend” (HTML/CSS/JS)
- “Backend – Flask API”
- “Image & PDF Processing Pipeline” (with steps like Upscaling, Deskewing, Contrast Enhancement, Thresholding, etc.)
- “OCR Engine” (Tesseract)
- “MySQL Database”
- “Debug Module/Logging”
- Rectangles for major components (frontend, backend, database)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Global Entities
    U("User"):::user
    FE("Frontend (HTML/CSS/JS)"):::frontend
    BE("Backend - Flask API"):::backend
    DB("MySQL Database"):::database

    %% Subgraph: API Endpoints
    subgraph "API Endpoints"
        UP("POST_/upload-invoice"):::api
        CF("POST_/confirm-invoice"):::api
        DI("GET_/debug-info"):::api
    end

    %% Subgraph: Image & PDF Processing Pipeline
    subgraph "Image & PDF Processing Pipeline"
        IP("Initial_Processing_(Upscale,Deskew)"):::process
        EN("Enhancement_(Grayscale,CLAHE,Thresholding)"):::process
        DS("Document_Specific_Processing"):::process
        OCR("OCR_Engine_(Tesseract)"):::process
        ED("Extracted_Data"):::process
    end

    %% Debug Module
    DBG("Debug_Module/Logging"):::debug

    %% Interactions between Components
    U -->|"uploads"| FE
    FE -->|"HTTP_Request"| BE
    BE -->|"handles"| UP
    BE -->|"handles"| CF
    BE -->|"handles"| DI

    %% Processing Pipeline Flow
    UP -->|"processes_file"| IP
    IP -->|"next_step"| EN
    EN -->|"next_step"| DS
    DS -->|"next_step"| OCR
    OCR -->|"generates"| ED

    %% Data flows to Database and Debug Module
    ED -->|"stores_data"| DB
    OCR -->|"debug_info"| DBG
    DBG -->|"available_for"| DI

    %% External Library References (Annotations)
    OCR ---|"uses_Tesseract"| OCR
    IP ---|"uses_pdf2image/Opencv"| EN

    %% Click Events
    click FE "https://github.com/shiv1810/bill-scanner-ocr/tree/main/frontend/"
    click BE "https://github.com/shiv1810/bill-scanner-ocr/blob/main/backend/app.py"

    %% Styles
    classDef user fill:#f5f5f5,stroke:#333,stroke-width:2px;
    classDef frontend fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef backend fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef api fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef process fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef database fill:#e6e6e6,stroke:#333,stroke-width:2px;
    classDef debug fill:#ffe680,stroke:#333,stroke-width:2px;
```
