# ruizguille/invoice-processing architecture

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

- Interactive diagram: https://gitdiagram.com/ruizguille/invoice-processing
- Repository: https://github.com/ruizguille/invoice-processing

## Overview

This is a command-line invoice-processing application. An operator runs the workflow over PDFs in the configured invoice directory: it converts each PDF’s first page to an image, asks GPT-4o to extract structured invoice data, validates and flattens the results, calculates overall and monthly financial summaries, and writes an Excel report. The graph separates extraction, data processing, and reporting stages; the prompt and configuration are supporting layers. Source excerpts show the main calls, but do not show runtime behavior beyond those excerpts.

Main entry points: [`app/extraction.py`](https://github.com/ruizguille/invoice-processing/blob/master/app/extraction.py) (Extraction orchestrator), [`app/main.py`](https://github.com/ruizguille/invoice-processing/blob/master/app/main.py) (Workflow runner), [`app/config.py`](https://github.com/ruizguille/invoice-processing/blob/master/app/config.py) (Application settings), [`app/processing.py`](https://github.com/ruizguille/invoice-processing/blob/master/app/processing.py) (Invoice dataframe builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Workflow entry"]
  node_workflow["Workflow runner<br/>[main.py]"]
end

subgraph group_extract["Invoice extraction"]
  node_pdf_conversion["PDF image conversion<br/>[extraction.py]"]
  node_extraction_orchestrator["Extraction orchestrator<br/>[extraction.py]"]
end

subgraph group_process["Data processing"]
  node_invoice_schema["Invoice validation schema<br/>[processing.py]"]
  node_invoice_flattening["Invoice flattening<br/>[processing.py]"]
  node_invoice_dataframe["Invoice dataframe builder<br/>[processing.py]"]
  node_financial_summary["Financial summaries<br/>[processing.py]"]
end

subgraph group_support["Configuration and reporting"]
  node_settings["Application settings<br/>[config.py]"]
  node_prompt["Extraction prompt<br/>[prompt.py]"]
  node_excel_report["Excel report generator<br/>[processing.py]"]
end

node_operator(("Operator"))
node_invoice_files["Invoice PDFs"]
node_openai["OpenAI GPT-4o"]
node_report_file["Excel report"]

node_operator -->|"runs"| node_workflow
node_workflow -->|"reads settings"| node_settings
node_workflow -->|"starts extraction"| node_extraction_orchestrator
node_settings -->|"sets input directory"| node_extraction_orchestrator
node_invoice_files -->|"reads PDFs"| node_extraction_orchestrator
node_extraction_orchestrator -->|"converts PDF"| node_pdf_conversion
node_extraction_orchestrator -->|"uses API key"| node_settings
node_extraction_orchestrator -->|"formats prompt"| node_prompt
node_extraction_orchestrator -->|"requests extraction"| node_openai
node_workflow -->|"builds dataframe"| node_invoice_dataframe
node_invoice_dataframe -->|"validates records"| node_invoice_schema
node_invoice_dataframe -->|"flattens records"| node_invoice_flattening
node_workflow -->|"calculates summaries"| node_financial_summary
node_workflow -->|"creates report"| node_excel_report
node_settings -->|"sets output path"| node_excel_report
node_excel_report -->|"writes workbook"| node_report_file

click node_workflow "https://github.com/ruizguille/invoice-processing/blob/master/app/main.py"
click node_invoice_files "https://github.com/ruizguille/invoice-processing/tree/master/data/invoices"
click node_settings "https://github.com/ruizguille/invoice-processing/blob/master/app/config.py"
click node_pdf_conversion "https://github.com/ruizguille/invoice-processing/blob/master/app/extraction.py"
click node_extraction_orchestrator "https://github.com/ruizguille/invoice-processing/blob/master/app/extraction.py"
click node_prompt "https://github.com/ruizguille/invoice-processing/blob/master/app/prompt.py"
click node_invoice_schema "https://github.com/ruizguille/invoice-processing/blob/master/app/processing.py"
click node_invoice_flattening "https://github.com/ruizguille/invoice-processing/blob/master/app/processing.py"
click node_invoice_dataframe "https://github.com/ruizguille/invoice-processing/blob/master/app/processing.py"
click node_financial_summary "https://github.com/ruizguille/invoice-processing/blob/master/app/processing.py"
click node_excel_report "https://github.com/ruizguille/invoice-processing/blob/master/app/processing.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_workflow toneBlue
class node_pdf_conversion,node_extraction_orchestrator toneAmber
class node_invoice_schema,node_invoice_flattening,node_invoice_dataframe,node_financial_summary toneMint
class node_settings,node_prompt,node_excel_report toneRose
class node_operator,node_openai,node_report_file toneIndigo
class node_invoice_files toneTeal
```

## Components

### Workflow entry

- [Workflow runner](https://github.com/ruizguille/invoice-processing/blob/master/app/main.py): `app/main.py`

### Invoice extraction

- [PDF image conversion](https://github.com/ruizguille/invoice-processing/blob/master/app/extraction.py): `app/extraction.py`
- [Extraction orchestrator](https://github.com/ruizguille/invoice-processing/blob/master/app/extraction.py): `app/extraction.py`

### Data processing

- [Invoice validation schema](https://github.com/ruizguille/invoice-processing/blob/master/app/processing.py): `app/processing.py`
- [Invoice flattening](https://github.com/ruizguille/invoice-processing/blob/master/app/processing.py): `app/processing.py`
- [Invoice dataframe builder](https://github.com/ruizguille/invoice-processing/blob/master/app/processing.py): `app/processing.py`
- [Financial summaries](https://github.com/ruizguille/invoice-processing/blob/master/app/processing.py): `app/processing.py`

### Configuration and reporting

- [Application settings](https://github.com/ruizguille/invoice-processing/blob/master/app/config.py): `app/config.py`
- [Extraction prompt](https://github.com/ruizguille/invoice-processing/blob/master/app/prompt.py): `app/prompt.py`
- [Excel report generator](https://github.com/ruizguille/invoice-processing/blob/master/app/processing.py): `app/processing.py`

### Other components

- **Operator**
- [Invoice PDFs](https://github.com/ruizguille/invoice-processing/tree/master/data/invoices): `data/invoices`
- **OpenAI GPT-4o**
- **Excel report**

## Connections

- Operator → Workflow runner: runs (evidence: `README.md`)
- Workflow runner → Application settings: reads settings (evidence: `app/main.py`)
- Workflow runner → Extraction orchestrator: starts extraction (evidence: `app/main.py`)
- Application settings → Extraction orchestrator: sets input directory (evidence: `app/main.py`)
- Invoice PDFs → Extraction orchestrator: reads PDFs (evidence: `app/extraction.py`)
- Extraction orchestrator → PDF image conversion: converts PDF (evidence: `app/extraction.py`)
- Extraction orchestrator → Application settings: uses API key (evidence: `app/extraction.py`)
- Extraction orchestrator → Extraction prompt: formats prompt (evidence: `app/extraction.py`)
- Extraction orchestrator → OpenAI GPT-4o: requests extraction (evidence: `app/extraction.py`)
- Workflow runner → Invoice dataframe builder: builds dataframe (evidence: `app/main.py`)
- Invoice dataframe builder → Invoice validation schema: validates records (evidence: `app/processing.py`)
- Invoice dataframe builder → Invoice flattening: flattens records (evidence: `app/processing.py`)
- Workflow runner → Financial summaries: calculates summaries (evidence: `app/main.py`)
- Workflow runner → Excel report generator: creates report (evidence: `app/main.py`)
- Application settings → Excel report generator: sets output path (evidence: `app/main.py`)
- Excel report generator → Excel report: writes workbook (evidence: `app/processing.py`)