# code84/invoice-ai architecture

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

- Interactive diagram: https://gitdiagram.com/code84/invoice-ai
- Repository: https://github.com/code84/invoice-ai

## Overview

InvoiceAI is an Accounts Payable application: an AP user uploads a PDF, the backend processes it into an explainable approval/review/rejection decision, and the frontend exposes progress, history, and invoice details. The graph preserves documented extraction, matching, rules, audit, and dashboard capabilities. Some subsystem links rely on README statements or the source index; unsampled implementation details are not inferred.

Main entry points: [`backend/app/services/pipeline.py`](https://github.com/code84/invoice-ai/blob/main/backend/app/services/pipeline.py) (Processing Orchestrator), [`backend/app/main.py`](https://github.com/code84/invoice-ai/blob/main/backend/app/main.py) (FastAPI Application), [`frontend_updated/lib/api.ts`](https://github.com/code84/invoice-ai/blob/main/frontend_updated/lib/api.ts) (Frontend API Client), [`backend/app/database.py`](https://github.com/code84/invoice-ai/blob/main/backend/app/database.py) (SQLAlchemy Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Interface"]
  node_landing["Product Overview<br/>[page.tsx]"]
  node_upload_ui["Invoice Upload<br/>[page.tsx]"]
  node_run_ui["Live Run Progress<br/>[page.tsx]"]
  node_dashboard_ui["Dashboard<br/>[page.tsx]"]
  node_history_ui["Invoice History<br/>[page.tsx]"]
  node_detail_ui["Invoice Detail<br/>[page.tsx]"]
  node_api_client["Frontend API Client<br/>[api.ts]"]
end

subgraph group_api["API and Data"]
  node_api_app["FastAPI Application<br/>[main.py]"]
  node_invoice_routes["Invoice Routes<br/>[invoices.py]"]
  node_dashboard_routes["Dashboard Routes<br/>[dashboard.py]"]
  node_vendor_routes["Vendor Routes<br/>[vendors.py]"]
  node_po_routes["Purchase Order Routes<br/>[purchase_orders.py]"]
  node_schemas["API Schemas<br/>[schemas.py]"]
  node_db[("SQLAlchemy Database<br/>[database.py]")]
  node_data_models["Invoice and Run Models<br/>[models.py]"]
end

subgraph group_processing["Invoice Processing"]
  node_pipeline["Processing Orchestrator<br/>[pipeline.py]"]
  node_pdf["PDF and OCR Extraction<br/>[pdf_extractor.py]"]
  node_ai["AI Field Extraction<br/>[ai_extractor.py]"]
  node_normalize["Normalization and Validation<br/>[normalizer.py]"]
  node_vendor_match["Vendor Verification<br/>[vendor_verifier.py]"]
  node_po_match["PO Matching<br/>[po_matcher.py]"]
  node_duplicates["Duplicate Detection"]
  node_rules["Business Rules<br/>[rules_engine.py]"]
  node_decision["Decision and Explanation<br/>[decision_engine.py]"]
  node_run_manager["Run and Audit Tracking<br/>[run_manager.py]"]
end

subgraph group_reference["AP Reference Data"]
  node_vendors["Vendor Master<br/>[models.py]"]
  node_purchase_orders["Purchase Orders<br/>[models.py]"]
end

node_ap_user(("AP User"))
node_llm{{"Gemini or OpenAI"}}
node_ocr_engine{{"Tesseract OCR"}}
node_pdf_files[("Uploaded PDFs")]

node_ap_user -->|"visits"| node_landing
node_ap_user -->|"submits PDF"| node_upload_ui
node_upload_ui -->|"requests upload"| node_api_client
node_api_client -->|"REST requests"| node_api_app
node_api_app -->|"registers routes"| node_invoice_routes
node_api_app -->|"registers routes"| node_dashboard_routes
node_api_app -->|"registers routes"| node_vendor_routes
node_api_app -->|"registers routes"| node_po_routes
node_api_app -->|"creates tables"| node_db
node_invoice_routes -->|"starts processing"| node_pipeline
node_invoice_routes -->|"creates run"| node_run_manager
node_invoice_routes -->|"reads and writes"| node_db
node_dashboard_routes -->|"queries stats"| node_db
node_vendor_routes -->|"queries vendors"| node_db
node_po_routes -->|"queries orders"| node_db
node_pipeline -->|"extracts PDF text"| node_pdf
node_pipeline -->|"extracts fields"| node_ai
node_pipeline -->|"normalizes fields"| node_normalize
node_pipeline -->|"verifies vendor"| node_vendor_match
node_pipeline -->|"matches PO"| node_po_match
node_pipeline -->|"checks duplicates"| node_duplicates
node_pipeline -->|"evaluates evidence"| node_rules
node_pipeline -->|"requests decision"| node_decision
node_pipeline -->|"records stages"| node_run_manager
node_ai -->|"requests extraction"| node_llm
node_pdf -->|"OCR fallback"| node_ocr_engine
node_pipeline -->|"stores uploaded PDF"| node_pdf_files
node_run_ui -->|"requests run status"| node_api_client
node_dashboard_ui -->|"requests dashboard data"| node_api_client
node_history_ui -->|"requests invoice history"| node_api_client
node_detail_ui -->|"requests invoice detail"| node_api_client
node_run_manager -->|"persists run records"| node_data_models
node_pipeline -->|"updates invoice"| node_data_models
node_vendor_match -->|"checks vendor master"| node_vendors
node_po_match -->|"checks PO data"| node_purchase_orders
node_rules -->|"supplies rule results"| node_decision

click node_landing "https://github.com/code84/invoice-ai/blob/main/frontend_updated/app/page.tsx"
click node_upload_ui "https://github.com/code84/invoice-ai/blob/main/frontend_updated/app/upload/page.tsx"
click node_run_ui "https://github.com/code84/invoice-ai/blob/main/frontend_updated/app/runs/%5Bid%5D/page.tsx"
click node_dashboard_ui "https://github.com/code84/invoice-ai/blob/main/frontend_updated/app/dashboard/page.tsx"
click node_history_ui "https://github.com/code84/invoice-ai/blob/main/frontend_updated/app/invoices/page.tsx"
click node_detail_ui "https://github.com/code84/invoice-ai/blob/main/frontend_updated/app/invoices/%5Bid%5D/page.tsx"
click node_api_client "https://github.com/code84/invoice-ai/blob/main/frontend_updated/lib/api.ts"
click node_api_app "https://github.com/code84/invoice-ai/blob/main/backend/app/main.py"
click node_invoice_routes "https://github.com/code84/invoice-ai/blob/main/backend/app/routers/invoices.py"
click node_dashboard_routes "https://github.com/code84/invoice-ai/blob/main/backend/app/routers/dashboard.py"
click node_vendor_routes "https://github.com/code84/invoice-ai/blob/main/backend/app/routers/vendors.py"
click node_po_routes "https://github.com/code84/invoice-ai/blob/main/backend/app/routers/purchase_orders.py"
click node_schemas "https://github.com/code84/invoice-ai/blob/main/backend/app/schemas/schemas.py"
click node_db "https://github.com/code84/invoice-ai/blob/main/backend/app/database.py"
click node_data_models "https://github.com/code84/invoice-ai/blob/main/backend/app/models/models.py"
click node_pipeline "https://github.com/code84/invoice-ai/blob/main/backend/app/services/pipeline.py"
click node_pdf "https://github.com/code84/invoice-ai/blob/main/backend/app/services/pdf_extractor.py"
click node_ai "https://github.com/code84/invoice-ai/blob/main/backend/app/services/ai_extractor.py"
click node_normalize "https://github.com/code84/invoice-ai/blob/main/backend/app/services/normalizer.py"
click node_vendor_match "https://github.com/code84/invoice-ai/blob/main/backend/app/services/vendor_verifier.py"
click node_po_match "https://github.com/code84/invoice-ai/blob/main/backend/app/services/po_matcher.py"
click node_duplicates "https://github.com/code84/invoice-ai/blob/main/backend/app/services/duplicate_detector.py"
click node_rules "https://github.com/code84/invoice-ai/blob/main/backend/app/services/rules_engine.py"
click node_decision "https://github.com/code84/invoice-ai/blob/main/backend/app/services/decision_engine.py"
click node_run_manager "https://github.com/code84/invoice-ai/blob/main/backend/app/services/run_manager.py"
click node_vendors "https://github.com/code84/invoice-ai/blob/main/backend/app/models/models.py"
click node_purchase_orders "https://github.com/code84/invoice-ai/blob/main/backend/app/models/models.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_landing,node_upload_ui,node_run_ui,node_dashboard_ui,node_history_ui,node_detail_ui,node_api_client,node_ap_user toneBlue
class node_api_app,node_invoice_routes,node_dashboard_routes,node_vendor_routes,node_po_routes,node_schemas,node_db,node_data_models,node_pdf_files toneAmber
class node_pipeline,node_pdf,node_ai,node_normalize,node_vendor_match,node_po_match,node_duplicates,node_rules,node_decision,node_run_manager toneMint
class node_vendors,node_purchase_orders toneRose
class node_llm,node_ocr_engine toneIndigo
```

## Components

### User Interface

- [Product Overview](https://github.com/code84/invoice-ai/blob/main/frontend_updated/app/page.tsx): `frontend_updated/app/page.tsx`
- [Invoice Upload](https://github.com/code84/invoice-ai/blob/main/frontend_updated/app/upload/page.tsx): `frontend_updated/app/upload/page.tsx`
- [Live Run Progress](https://github.com/code84/invoice-ai/blob/main/frontend_updated/app/runs/%5Bid%5D/page.tsx): `frontend_updated/app/runs/[id]/page.tsx`
- [Dashboard](https://github.com/code84/invoice-ai/blob/main/frontend_updated/app/dashboard/page.tsx): `frontend_updated/app/dashboard/page.tsx`
- [Invoice History](https://github.com/code84/invoice-ai/blob/main/frontend_updated/app/invoices/page.tsx): `frontend_updated/app/invoices/page.tsx`
- [Invoice Detail](https://github.com/code84/invoice-ai/blob/main/frontend_updated/app/invoices/%5Bid%5D/page.tsx): `frontend_updated/app/invoices/[id]/page.tsx`
- [Frontend API Client](https://github.com/code84/invoice-ai/blob/main/frontend_updated/lib/api.ts): `frontend_updated/lib/api.ts`

### API and Data

- [FastAPI Application](https://github.com/code84/invoice-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Invoice Routes](https://github.com/code84/invoice-ai/blob/main/backend/app/routers/invoices.py): `backend/app/routers/invoices.py`
- [Dashboard Routes](https://github.com/code84/invoice-ai/blob/main/backend/app/routers/dashboard.py): `backend/app/routers/dashboard.py`
- [Vendor Routes](https://github.com/code84/invoice-ai/blob/main/backend/app/routers/vendors.py): `backend/app/routers/vendors.py`
- [Purchase Order Routes](https://github.com/code84/invoice-ai/blob/main/backend/app/routers/purchase_orders.py): `backend/app/routers/purchase_orders.py`
- [API Schemas](https://github.com/code84/invoice-ai/blob/main/backend/app/schemas/schemas.py): `backend/app/schemas/schemas.py`
- [SQLAlchemy Database](https://github.com/code84/invoice-ai/blob/main/backend/app/database.py): `backend/app/database.py`
- [Invoice and Run Models](https://github.com/code84/invoice-ai/blob/main/backend/app/models/models.py): `backend/app/models/models.py`

### Invoice Processing

- [Processing Orchestrator](https://github.com/code84/invoice-ai/blob/main/backend/app/services/pipeline.py): `backend/app/services/pipeline.py`
- [PDF and OCR Extraction](https://github.com/code84/invoice-ai/blob/main/backend/app/services/pdf_extractor.py): `backend/app/services/pdf_extractor.py`
- [AI Field Extraction](https://github.com/code84/invoice-ai/blob/main/backend/app/services/ai_extractor.py): `backend/app/services/ai_extractor.py`
- [Normalization and Validation](https://github.com/code84/invoice-ai/blob/main/backend/app/services/normalizer.py): `backend/app/services/normalizer.py`
- [Vendor Verification](https://github.com/code84/invoice-ai/blob/main/backend/app/services/vendor_verifier.py): `backend/app/services/vendor_verifier.py`
- [PO Matching](https://github.com/code84/invoice-ai/blob/main/backend/app/services/po_matcher.py): `backend/app/services/po_matcher.py`
- [Duplicate Detection](https://github.com/code84/invoice-ai/blob/main/backend/app/services/duplicate_detector.py): `backend/app/services/duplicate_detector.py`
- [Business Rules](https://github.com/code84/invoice-ai/blob/main/backend/app/services/rules_engine.py): `backend/app/services/rules_engine.py`
- [Decision and Explanation](https://github.com/code84/invoice-ai/blob/main/backend/app/services/decision_engine.py): `backend/app/services/decision_engine.py`
- [Run and Audit Tracking](https://github.com/code84/invoice-ai/blob/main/backend/app/services/run_manager.py): `backend/app/services/run_manager.py`

### AP Reference Data

- [Vendor Master](https://github.com/code84/invoice-ai/blob/main/backend/app/models/models.py): `backend/app/models/models.py`
- [Purchase Orders](https://github.com/code84/invoice-ai/blob/main/backend/app/models/models.py): `backend/app/models/models.py`

### Other components

- **AP User**
- **Gemini or OpenAI**
- **Tesseract OCR**
- **Uploaded PDFs**

## Connections

- AP User → Product Overview: visits
- AP User → Invoice Upload: submits PDF
- Invoice Upload → Frontend API Client: requests upload
- Frontend API Client → FastAPI Application: REST requests
- FastAPI Application → Invoice Routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI Application → Dashboard Routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI Application → Vendor Routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI Application → Purchase Order Routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI Application → SQLAlchemy Database: creates tables (evidence: `backend/app/main.py`)
- Invoice Routes → Processing Orchestrator: starts processing (evidence: `backend/app/routers/invoices.py`)
- Invoice Routes → Run and Audit Tracking: creates run (evidence: `backend/app/routers/invoices.py`)
- Invoice Routes → SQLAlchemy Database: reads and writes (evidence: `backend/app/routers/invoices.py`)
- Dashboard Routes → SQLAlchemy Database: queries stats (evidence: `backend/app/routers/dashboard.py`)
- Vendor Routes → SQLAlchemy Database: queries vendors (evidence: `backend/app/routers/vendors.py`)
- Purchase Order Routes → SQLAlchemy Database: queries orders (evidence: `backend/app/routers/purchase_orders.py`)
- Processing Orchestrator → PDF and OCR Extraction: extracts PDF text (evidence: `backend/app/services/pipeline.py`)
- Processing Orchestrator → AI Field Extraction: extracts fields (evidence: `backend/app/services/pipeline.py`)
- Processing Orchestrator → Normalization and Validation: normalizes fields (evidence: `backend/app/services/pipeline.py`)
- Processing Orchestrator → Vendor Verification: verifies vendor (evidence: `backend/app/services/pipeline.py`)
- Processing Orchestrator → PO Matching: matches PO (evidence: `backend/app/services/pipeline.py`)
- Processing Orchestrator → Duplicate Detection: checks duplicates (evidence: `backend/app/services/pipeline.py`)
- Processing Orchestrator → Business Rules: evaluates evidence (evidence: `backend/app/services/pipeline.py`)
- Processing Orchestrator → Decision and Explanation: requests decision (evidence: `backend/app/services/pipeline.py`)
- Processing Orchestrator → Run and Audit Tracking: records stages (evidence: `backend/app/services/pipeline.py`)
- AI Field Extraction → Gemini or OpenAI: requests extraction
- PDF and OCR Extraction → Tesseract OCR: OCR fallback
- Processing Orchestrator → Uploaded PDFs: stores uploaded PDF
- Live Run Progress → Frontend API Client: requests run status
- Dashboard → Frontend API Client: requests dashboard data
- Invoice History → Frontend API Client: requests invoice history
- Invoice Detail → Frontend API Client: requests invoice detail
- Run and Audit Tracking → Invoice and Run Models: persists run records (evidence: `backend/app/services/run_manager.py`)
- Processing Orchestrator → Invoice and Run Models: updates invoice (evidence: `backend/app/services/pipeline.py`)
- Vendor Verification → Vendor Master: checks vendor master (evidence: `backend/app/services/pipeline.py`)
- PO Matching → Purchase Orders: checks PO data (evidence: `backend/app/services/pipeline.py`)
- Business Rules → Decision and Explanation: supplies rule results (evidence: `backend/app/services/decision_engine.py`)
