# itvincent-git/invoice_renamer architecture

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

- Interactive diagram: https://gitdiagram.com/itvincent-git/invoice_renamer
- Repository: https://github.com/itvincent-git/invoice_renamer

## Overview

##### Project type and purpose
- This is a Python-based command-line utility (“Invoice Renamer”) that processes invoice files (PDF/JPG) using OCR to extract date & amount, then renames them into a standardized format and writes them to a ‘rename’ directory.

##### File structure
- Top-level files:
- main.py – CLI entry point
- paddle/ – contains an example/demo script (paddle-demo.py) showing how OCR is invoked
- pyproject.toml & uv.lock – dependency and environment specification
- README.md, LICENSE, .gitignore – docs and metadata
- No separate “frontend” or “backend” folders: this is a single-process tool.

##### README for additional insights
- Dependencies: paddleocr, pdf2image, argparse, Python ≥3.11
- Features: single-file or directory processing, Chinese invoice support
- Output: standardized filename `YYYYMMDD_AMOUNT元.pdf` in a ‘rename’ directory

##### Main components & their relationships
a. CLI / main.py
– Parses arguments (file or directory path) via argparse
– Invokes the Controller / Orchestrator
b. File Handler
– Walks directories, filters for PDF/JPG files
– For PDFs, delegates to PDF Converter
c. PDF Converter (pdf2image)
– Converts PDF pages into images for OCR
d. OCR Processor (PaddleOCR)
– Runs text recognition on images or JPGs
e. Data Extractor
– Parses OCR results to find invoice date & amount
f. Renamer Service
– Constructs new filename
– Writes/moves file into ‘rename’ directory
g. Demo Script (paddle/paddle-demo.py)
– Stand-alone example of OCR usage

Data flow:
[CLI/main.py] → [File Handler] → (PDF?), → [PDF Converter] → [OCR Processor] → [Data Extractor] → [Renamer Service] → [Output Directory]

##### Architectural patterns & design principles
- Single-process, modular pipeline
- Separation of concerns: I/O, conversion, OCR, parsing, renaming
- Dependency injection of OCR engine via a demo module
- Configured by pyproject.toml & uv.lock for reproducibility

- External libraries/frameworks at the periphery (pdf2image, PaddleOCR, argparse).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core components
    CLI["CLI Entry Point<br>(main.py)"]:::cli
    FileHandler["File Handler"]:::filehandler
    PDFConverter["PDF Converter<br>(pdf2image)"]:::converter
    OCR["OCR Processor<br>(PaddleOCR)"]:::ocr
    Extractor["Data Extractor"]:::extractor
    Renamer["Renamer Service"]:::renamer
    Output["Output Directory<br>('rename')"]:::external

    %% Demo
    Demo["Demo Script<br>(paddle-demo.py)"]:::external

    %% External libraries
    Lib_arg["argparse"]:::external
    Lib_pdf2["pdf2image"]:::external
    Lib_paddle["PaddleOCR"]:::external

    %% Configuration & Documentation
    Config["Config<br>(pyproject.toml<br>uv.lock)"]:::doc
    Docs["Docs & Metadata<br>(README.md<br>LICENSE<br>.gitignore)"]:::doc

    %% Data flow
    CLI -->|"parses args"| FileHandler
    FileHandler -->|"filter files"| PDFConverter
    PDFConverter -->|"PDF→images"| OCR
    OCR -->|"text output"| Extractor
    Extractor -->|"extract date&amount"| Renamer
    Renamer -->|"rename(input,output)"| Output

    %% Dependency usage
    FileHandler -->|"uses argparse"| Lib_arg
    PDFConverter -->|"uses pdf2image"| Lib_pdf2
    OCR -->|"uses PaddleOCR"| Lib_paddle
    CLI -.->|"demo example"| Demo

    %% Config & Docs references
    CLI -.-> Config
    CLI -.-> Docs

    %% Click events
    click CLI "https://github.com/itvincent-git/invoice_renamer/blob/main/main.py"
    click FileHandler "https://github.com/itvincent-git/invoice_renamer/blob/main/main.py"
    click PDFConverter "https://github.com/itvincent-git/invoice_renamer/blob/main/main.py"
    click OCR "https://github.com/itvincent-git/invoice_renamer/blob/main/main.py"
    click Extractor "https://github.com/itvincent-git/invoice_renamer/blob/main/main.py"
    click Renamer "https://github.com/itvincent-git/invoice_renamer/blob/main/main.py"
    click Demo "https://github.com/itvincent-git/invoice_renamer/blob/main/paddle/paddle-demo.py"
    click Config "https://github.com/itvincent-git/invoice_renamer/blob/main/pyproject.toml"
    click Docs "https://github.com/itvincent-git/invoice_renamer/blob/main/README.md"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#005cbf;
    classDef filehandler fill:#d4edda,stroke:#155724;
    classDef converter fill:#ffe5b4,stroke:#e69500;
    classDef ocr fill:#e2d4f0,stroke:#6f42c1;
    classDef extractor fill:#fff3cd,stroke:#856404;
    classDef renamer fill:#d1ecf1,stroke:#0c5460;
    classDef external fill:#f8f9fa,stroke:#d6d8db,stroke-dasharray: 5 5;
    classDef doc fill:#f0f0f0,stroke:#888888;
```
