# aum8/bank-statement_extraction architecture

> Architecture diagram of the GitHub repository aum8/bank-statement_extraction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aum8/bank-statement_extraction
- Repository: https://github.com/aum8/bank-statement_extraction

## Overview

##### Project Type and Purpose
- This is a Python-based *data-extraction tool* that reads bank-statement PDFs and outputs structured JSON.
- It exposes two “front ends”: a terminal/CLI script (`extractor.py`) and a web API (`fast_api.py` using FastAPI).
- Under the hood it uses OCR (Tesseract) plus optional LLM/ML back-ends (local model API or OpenRouter/Gemini).

A. Interfaces
- CLI Interface (extractor.py)
- HTTP API (FastAPI app in fast_api.py) + Swagger UI
B. Core Extraction Engine
- PDF loader / preprocessor
- OCR processor (Tesseract)
- Header parser (IFSC, account no.)
- Table parser (transactions)
- JSON builder
C. External Services / Models
- Local OCR binary (Tesseract OCR)
- Optional local ML model endpoint (`LOCAL_MODEL_API_BASE`)
- Open-source model via OpenRouter/Gemini API
D. Configuration & Environment
- `.env` variables (API keys, local model URL, Tesseract path)
E. Outputs
- JSON file (`output.json`) for CLI
- JSON HTTP response for API

##### Data Flow and Relationships
- CLI or HTTP client → PDF input
- Pass PDF to Core Extraction Engine
- Preprocess → OCR → parsers → JSON builder
- Core Engine may call either:
- Local Tesseract binary for OCR
- Local model API or OpenRouter/Gemini for advanced extraction tasks
- Engine returns JSON to:
- CLI (writes `output.json`)
- FastAPI (returns HTTP response)

##### Architectural Patterns & Design Principles
- **Separation of Concerns**: interfaces (CLI vs. HTTP) are thin wrappers over a shared core extraction module.
- **Pluggable Back-Ends**: OCR/ML components abstracted behind environment-configurable endpoints.
- **Single-Process Service**: no separate microservices—both modes run in the same Python process but could be split if scaling needed.

##### Technologies and Frameworks
- Python 3.x
- FastAPI (HTTP server, swagger docs)
- Tesseract OCR (via pytesseract or similar)
- PDF parsing library (e.g., pdfplumber or PyPDF2)
- HTTP client for external model APIs (requests or httpx)
- Uvicorn (ASGI server)

3) Inside Extraction Engine, subdivide into:
- PDF Preprocessor → OCR Processor → Data Parsers → JSON Builder

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interfaces
    subgraph "Interfaces"
        style Interfaces fill:#e0f7fa,stroke:#006064
        CLI["CLI<br>(extractor.py)"]:::interface
        HTTP["HTTP API<br>(fast_api.py + Swagger UI)"]:::interface
    end

    %% Extraction Engine
    subgraph "Extraction Engine"
        style Extraction Engine fill:#bbdefb,stroke:#0d47a1
        Preprocessor["PDF Preprocessor"]:::internal
        OCR["OCR Processor"]:::internal
        Parsers["Data Parsers<br>(Header & Table)"]:::internal
        JSONBuilder["JSON Builder"]:::internal
        Preprocessor -->|PDF| OCR
        OCR -->|text/images| Parsers
        Parsers -->|parsed data| JSONBuilder
    end

    %% External Services
    subgraph "External Services"
        style External Services fill:#ffe0b2,stroke:#e65100
        Tesseract["Tesseract OCR<br>(local binary)"]:::external
        LocalModel["Local Model API"]:::external
        OpenRouter["OpenRouter / Gemini API"]:::external
    end

    %% Outputs
    subgraph "Outputs"
        style Outputs fill:#f3e5f5,stroke:#4a148c
        JSONFile["JSON File<br>(output.json)"]:::output
        HTTPResp["JSON HTTP Response"]:::output
    end

    %% Data Flow
    CLI -->|PDF| Preprocessor
    HTTP -->|PDF via HTTP| Preprocessor
    OCR --> Tesseract
    JSONBuilder -->|optional advanced extract| LocalModel
    JSONBuilder -->|optional advanced extract| OpenRouter
    JSONBuilder -->|JSON| JSONFile
    JSONBuilder -->|JSON| HTTPResp

    %% Click Events
    click CLI "https://github.com/aum8/bank-statement_extraction/blob/main/extractor.py"
    click HTTP "https://github.com/aum8/bank-statement_extraction/blob/main/fast_api.py"

    %% Styles
    classDef interface fill:#c8e6c9,stroke:#256029
    classDef internal fill:#bbdefb,stroke:#0d47a1
    classDef external fill:#ffe0b2,stroke:#e65100,stroke-dasharray: 5 5
    classDef output fill:#f3e5f5,stroke:#4a148c

    %% Legend
    subgraph "Legend"
        direction TB
        A["Interfaces (green)"]:::interface
        B["Internal Modules (blue)"]:::internal
        C["External Services (orange dashed)"]:::external
        D["Outputs (purple)"]:::output
    end
```
