# shivamkrsingh01/invoice_automation architecture

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

- Interactive diagram: https://gitdiagram.com/shivamkrsingh01/invoice_automation
- Repository: https://github.com/shivamkrsingh01/invoice_automation

## Overview

AI Invoice Automation polls Outlook, extracts and normalizes invoice data, deduplicates it, and stores it in PostgreSQL; an authenticated React dashboard exposes invoice browsing, validation, sync controls, and Q&A. The README documents the end-to-end processing stages, while excerpts show API dispatch, session authentication, extraction helpers, and frontend API calls. Several backend internals are unsampled, so their documented connections use README evidence. A separate watchdog monitors application/database health and can alert through Telegram.

Main entry points: [`app/services/invoice_processor.py`](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/invoice_processor.py) (Invoice pipeline), [`invoice-ui/src/api/client.js`](https://github.com/shivamkrsingh01/invoice_automation/blob/main/invoice-ui/src/api/client.js) (API client), [`app/api/routes.py`](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/api/routes.py) (API routes), [`app/services/postgres_storage_service.py`](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/postgres_storage_service.py) (Invoice storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Email processing"]
  node_processor["Invoice pipeline"]
  node_graph["Mail connector<br/>[graph_service.py]"]
  node_documents["Document reader"]
  node_gemini["Gemini extraction"]
  node_freeextract["OCR extraction backup"]
  node_tables["Table extraction"]
end

subgraph group_backend["Invoice backend"]
  node_main["App runtime<br/>[main.py]"]
  node_validation["Field validation<br/>[validation.py]"]
  node_dedup["Invoice deduplication"]
  node_timestamps["Sync checkpoint"]
  node_invoice["Invoice model<br/>[invoice.py]"]
  node_storage[("Invoice storage")]
  node_settings["App settings<br/>[settings.py]"]
end

subgraph group_api["API and access"]
  node_routes["API routes<br/>[routes.py]"]
  node_auth["Session authentication<br/>[auth_service.py]"]
  node_qa["Invoice Q&amp;A<br/>[qa_service.py]"]
end

subgraph group_frontend["Admin dashboard"]
  node_client["API client<br/>[client.js]"]
  node_authguard["Protected routes<br/>[RequireAuth.jsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_invoices["Invoice pages<br/>[Invoices.jsx]"]
  node_validationpage["Validation page<br/>[Validation.jsx]"]
  node_qapage["Q&amp;A page<br/>[QA.jsx]"]
end

subgraph group_monitoring["Stability monitoring"]
  node_monitor["Health watchdog<br/>[monitor.py]"]
  node_notifier["Telegram notifier"]
end

node_mailbox(("Outlook mailbox"))
node_postgres[("PostgreSQL")]
node_browser(("Admin user"))
node_telegram["Telegram"]

node_main -->|"mounts routes"| node_routes
node_main -->|"runs polling"| node_processor
node_main -->|"reads settings"| node_settings
node_mailbox -->|"provides mail"| node_graph
node_processor -->|"fetches emails"| node_graph
node_processor -->|"reads attachments"| node_documents
node_processor -->|"extracts fields"| node_gemini
node_freeextract -->|"parses tables"| node_tables
node_processor -->|"normalizes fields"| node_validation
node_processor -->|"checks duplicates"| node_dedup
node_processor -->|"advances checkpoint"| node_timestamps
node_processor -->|"stores invoices"| node_storage
node_storage -->|"reads and writes"| node_postgres
node_processor -.->|"uses invoice records"| node_invoice
node_routes -->|"checks sessions"| node_auth
node_routes -->|"triggers processing"| node_processor
node_routes -->|"queries invoices"| node_storage
node_routes -->|"dispatches questions"| node_qa
node_qa -->|"reads invoice data"| node_storage
node_browser -->|"uses dashboard"| node_client
node_client -->|"calls API"| node_routes
node_authguard -->|"checks session"| node_client
node_dashboard -.->|"requests dashboard data"| node_client
node_invoices -.->|"requests invoice data"| node_client
node_validationpage -.->|"requests validation data"| node_client
node_qapage -.->|"submits questions"| node_client
node_monitor -->|"checks database"| node_postgres
node_monitor -->|"sends alerts"| node_notifier
node_notifier -->|"delivers messages"| node_telegram

click node_main "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/main.py"
click node_processor "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/invoice_processor.py"
click node_graph "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/graph_service.py"
click node_documents "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/document_processor.py"
click node_gemini "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/gemini_extraction_service.py"
click node_freeextract "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/free_extraction_service.py"
click node_tables "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/utils/table_extraction.py"
click node_validation "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/utils/validation.py"
click node_dedup "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/utils/document_dedup_tracker.py"
click node_timestamps "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/utils/timestamp_tracker.py"
click node_invoice "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/models/invoice.py"
click node_storage "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/postgres_storage_service.py"
click node_settings "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/config/settings.py"
click node_routes "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/api/routes.py"
click node_auth "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/auth_service.py"
click node_qa "https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/qa_service.py"
click node_client "https://github.com/shivamkrsingh01/invoice_automation/blob/main/invoice-ui/src/api/client.js"
click node_authguard "https://github.com/shivamkrsingh01/invoice_automation/blob/main/invoice-ui/src/components/RequireAuth.jsx"
click node_dashboard "https://github.com/shivamkrsingh01/invoice_automation/blob/main/invoice-ui/src/pages/Dashboard.jsx"
click node_invoices "https://github.com/shivamkrsingh01/invoice_automation/blob/main/invoice-ui/src/pages/Invoices.jsx"
click node_validationpage "https://github.com/shivamkrsingh01/invoice_automation/blob/main/invoice-ui/src/pages/Validation.jsx"
click node_qapage "https://github.com/shivamkrsingh01/invoice_automation/blob/main/invoice-ui/src/pages/QA.jsx"
click node_monitor "https://github.com/shivamkrsingh01/invoice_automation/blob/main/stability_monitor/monitor.py"
click node_notifier "https://github.com/shivamkrsingh01/invoice_automation/blob/main/stability_monitor/telegram_notifier.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_processor,node_graph,node_documents,node_gemini,node_freeextract,node_tables,node_browser toneBlue
class node_main,node_validation,node_dedup,node_timestamps,node_invoice,node_storage,node_settings,node_postgres toneAmber
class node_routes,node_auth,node_qa toneMint
class node_client,node_authguard,node_dashboard,node_invoices,node_validationpage,node_qapage toneRose
class node_monitor,node_notifier,node_mailbox,node_telegram toneIndigo
```

## Components

### Email processing

- [Invoice pipeline](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/invoice_processor.py): `app/services/invoice_processor.py`
- [Mail connector](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/graph_service.py): `app/services/graph_service.py`
- [Document reader](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/document_processor.py): `app/services/document_processor.py`
- [Gemini extraction](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/gemini_extraction_service.py): `app/services/gemini_extraction_service.py`
- [OCR extraction backup](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/free_extraction_service.py): `app/services/free_extraction_service.py`
- [Table extraction](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/utils/table_extraction.py): `app/utils/table_extraction.py`

### Invoice backend

- [App runtime](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/main.py): `app/main.py`
- [Field validation](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/utils/validation.py): `app/utils/validation.py`
- [Invoice deduplication](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/utils/document_dedup_tracker.py): `app/utils/document_dedup_tracker.py`
- [Sync checkpoint](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/utils/timestamp_tracker.py): `app/utils/timestamp_tracker.py`
- [Invoice model](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/models/invoice.py): `app/models/invoice.py`
- [Invoice storage](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/postgres_storage_service.py): `app/services/postgres_storage_service.py`
- [App settings](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/config/settings.py): `app/config/settings.py`

### API and access

- [API routes](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/api/routes.py): `app/api/routes.py`
- [Session authentication](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/auth_service.py): `app/services/auth_service.py`
- [Invoice Q&A](https://github.com/shivamkrsingh01/invoice_automation/blob/main/app/services/qa_service.py): `app/services/qa_service.py`

### Admin dashboard

- [API client](https://github.com/shivamkrsingh01/invoice_automation/blob/main/invoice-ui/src/api/client.js): `invoice-ui/src/api/client.js`
- [Protected routes](https://github.com/shivamkrsingh01/invoice_automation/blob/main/invoice-ui/src/components/RequireAuth.jsx): `invoice-ui/src/components/RequireAuth.jsx`
- [Dashboard](https://github.com/shivamkrsingh01/invoice_automation/blob/main/invoice-ui/src/pages/Dashboard.jsx): `invoice-ui/src/pages/Dashboard.jsx`
- [Invoice pages](https://github.com/shivamkrsingh01/invoice_automation/blob/main/invoice-ui/src/pages/Invoices.jsx): `invoice-ui/src/pages/Invoices.jsx`
- [Validation page](https://github.com/shivamkrsingh01/invoice_automation/blob/main/invoice-ui/src/pages/Validation.jsx): `invoice-ui/src/pages/Validation.jsx`
- [Q&A page](https://github.com/shivamkrsingh01/invoice_automation/blob/main/invoice-ui/src/pages/QA.jsx): `invoice-ui/src/pages/QA.jsx`

### Stability monitoring

- [Health watchdog](https://github.com/shivamkrsingh01/invoice_automation/blob/main/stability_monitor/monitor.py): `stability_monitor/monitor.py`
- [Telegram notifier](https://github.com/shivamkrsingh01/invoice_automation/blob/main/stability_monitor/telegram_notifier.py): `stability_monitor/telegram_notifier.py`

### Other components

- **Outlook mailbox**
- **PostgreSQL**
- **Admin user**
- **Telegram**

## Connections

- App runtime → API routes: mounts routes (evidence: `app/main.py`)
- App runtime → Invoice pipeline: runs polling (evidence: `app/main.py`)
- App runtime → App settings: reads settings (evidence: `app/main.py`)
- Outlook mailbox → Mail connector: provides mail
- Invoice pipeline → Mail connector: fetches emails
- Invoice pipeline → Document reader: reads attachments
- Invoice pipeline → Gemini extraction: extracts fields (evidence: `app/services/gemini_extraction_service.py`)
- OCR extraction backup → Table extraction: parses tables (evidence: `app/services/free_extraction_service.py`)
- Invoice pipeline → Field validation: normalizes fields
- Invoice pipeline → Invoice deduplication: checks duplicates
- Invoice pipeline → Sync checkpoint: advances checkpoint
- Invoice pipeline → Invoice storage: stores invoices
- Invoice storage → PostgreSQL: reads and writes
- Invoice pipeline → Invoice model: uses invoice records
- API routes → Session authentication: checks sessions (evidence: `app/api/routes.py`)
- API routes → Invoice pipeline: triggers processing (evidence: `app/api/routes.py`)
- API routes → Invoice storage: queries invoices (evidence: `app/api/routes.py`)
- API routes → Invoice Q&A: dispatches questions (evidence: `app/api/routes.py`)
- Invoice Q&A → Invoice storage: reads invoice data
- Admin user → API client: uses dashboard
- API client → API routes: calls API (evidence: `invoice-ui/src/api/client.js`)
- Protected routes → API client: checks session (evidence: `invoice-ui/src/components/RequireAuth.jsx`)
- Dashboard → API client: requests dashboard data
- Invoice pages → API client: requests invoice data
- Validation page → API client: requests validation data
- Q&A page → API client: submits questions
- Health watchdog → PostgreSQL: checks database (evidence: `stability_monitor/monitor.py`)
- Health watchdog → Telegram notifier: sends alerts (evidence: `stability_monitor/monitor.py`)
- Telegram notifier → Telegram: delivers messages (evidence: `stability_monitor/telegram_notifier.py`)
