# khanh02-vin/ai-invoice-billing architecture

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

- Interactive diagram: https://gitdiagram.com/khanh02-vin/ai-invoice-billing
- Repository: https://github.com/khanh02-vin/ai-invoice-billing

## Overview

Invoice & Billing System provides a browser workflow for signing in, uploading or managing invoices, and viewing reports. The central backend path accepts an upload, extracts bilingual invoice fields (with OCR and optional LLM fallback), and persists user-scoped records in SQLite; users can then list or update invoices and obtain monthly reports. Separate capabilities include authentication hardening, organizations/RBAC, billing, vector search, PDF export, metrics, and file storage. Edges reflect README statements and shown imports/calls; several documented subsystem details were not sampled, so their internal links are omitted.

Main entry points: [`src/app.py`](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/app.py) (FastAPI application), [`src/routers/search.py`](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/routers/search.py) (Invoice search API), [`frontend/src/App.jsx`](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/frontend/src/App.jsx) (React application), [`frontend/src/api.js`](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/frontend/src/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["React application<br/>[App.jsx]"]
  node_invoice_ui["Invoice dashboard<br/>[Invoices.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_invoice["Invoice workflow"]
  node_api["FastAPI application<br/>[app.py]"]
  node_upload["Upload validation<br/>[upload.py]"]
  node_extractor["Invoice extraction<br/>[extractor.py]"]
  node_llm["LLM fallback<br/>[base.py]"]
  node_invoice_model["Invoice domain<br/>[models.py]"]
  node_invoice_repo["Invoice repository<br/>[repository.py]"]
  node_sqlite[("SQLite database<br/>[db.py]")]
  node_file_storage["Original file storage<br/>[storage.py]"]
  node_pdf["PDF reports<br/>[pdf_exporter.py]"]
end

subgraph group_identity["Identity and tenancy"]
  node_auth["JWT security<br/>[security.py]"]
  node_users["User repository<br/>[users.py]"]
  node_auth_ext["Auth hardening<br/>[auth_ext.py]"]
  node_orgs["Organizations and RBAC<br/>[orgs.py]"]
  node_org_store["Organization storage<br/>[orgs.py]"]
end

subgraph group_platform["Billing and platform"]
  node_search_api["Invoice search API<br/>[search.py]"]
  node_vector_search["Vector search<br/>[vector_store.py]"]
  node_billing_api["Billing API<br/>[billing.py]"]
  node_billing_provider["Payment provider<br/>[provider.py]"]
  node_billing_repo[("Billing repository<br/>[repository.py]")]
  node_metrics["Prometheus metrics<br/>[metrics.py]"]
end

node_user(("Invoice user"))

node_user -->|"uses"| node_web
node_web -->|"renders"| node_invoice_ui
node_invoice_ui -->|"calls"| node_api_client
node_web -->|"checks session"| node_api_client
node_api_client -->|"HTTP requests"| node_api
node_api -->|"verifies tokens"| node_auth
node_api -->|"resolves user"| node_users
node_api -->|"validates upload"| node_upload
node_api -->|"extracts fields"| node_extractor
node_extractor -->|"fallback extraction"| node_llm
node_api -->|"validates records"| node_invoice_model
node_api -->|"stores and queries"| node_invoice_repo
node_invoice_repo -->|"persists invoices"| node_sqlite
node_api -->|"stores uploads"| node_file_storage
node_api -->|"exports reports"| node_pdf
node_auth_ext -->|"uses token helpers"| node_auth
node_auth_ext -->|"updates credentials"| node_users
node_orgs -->|"reads and writes"| node_org_store
node_search_api -->|"verifies tokens"| node_auth
node_search_api -->|"loads invoices"| node_invoice_repo
node_search_api -->|"queries index"| node_vector_search
node_billing_api -->|"dispatches payments"| node_billing_provider
node_billing_api -->|"persists billing"| node_billing_repo
node_api -->|"serves metrics"| node_metrics

click node_web "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/frontend/src/App.jsx"
click node_invoice_ui "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/frontend/src/Invoices.jsx"
click node_api_client "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/frontend/src/api.js"
click node_api "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/app.py"
click node_upload "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/upload.py"
click node_extractor "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/extract/extractor.py"
click node_llm "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/llm/base.py"
click node_invoice_model "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/domain/models.py"
click node_invoice_repo "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/store/repository.py"
click node_sqlite "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/store/db.py"
click node_file_storage "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/store/storage.py"
click node_pdf "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/reports/pdf_exporter.py"
click node_auth "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/auth/security.py"
click node_users "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/store/users.py"
click node_auth_ext "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/routers/auth_ext.py"
click node_orgs "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/routers/orgs.py"
click node_org_store "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/store/orgs.py"
click node_search_api "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/routers/search.py"
click node_vector_search "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/search/vector_store.py"
click node_billing_api "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/routers/billing.py"
click node_billing_provider "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/billing/provider.py"
click node_billing_repo "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/billing/repository.py"
click node_metrics "https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/observability/metrics.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_web,node_invoice_ui,node_api_client,node_user toneBlue
class node_api,node_upload,node_extractor,node_llm,node_invoice_model,node_invoice_repo,node_sqlite,node_file_storage,node_pdf toneAmber
class node_auth,node_users,node_auth_ext,node_orgs,node_org_store toneMint
class node_search_api,node_vector_search,node_billing_api,node_billing_provider,node_billing_repo,node_metrics toneRose
```

## Components

### Web client

- [React application](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Invoice dashboard](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/frontend/src/Invoices.jsx): `frontend/src/Invoices.jsx`
- [API client](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/frontend/src/api.js): `frontend/src/api.js`

### Invoice workflow

- [FastAPI application](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/app.py): `src/app.py`
- [Upload validation](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/upload.py): `src/upload.py`
- [Invoice extraction](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/extract/extractor.py): `src/extract/extractor.py`
- [LLM fallback](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/llm/base.py): `src/llm/base.py`
- [Invoice domain](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/domain/models.py): `src/domain/models.py`
- [Invoice repository](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/store/repository.py): `src/store/repository.py`
- [SQLite database](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/store/db.py): `src/store/db.py`
- [Original file storage](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/store/storage.py): `src/store/storage.py`
- [PDF reports](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/reports/pdf_exporter.py): `src/reports/pdf_exporter.py`

### Identity and tenancy

- [JWT security](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/auth/security.py): `src/auth/security.py`
- [User repository](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/store/users.py): `src/store/users.py`
- [Auth hardening](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/routers/auth_ext.py): `src/routers/auth_ext.py`
- [Organizations and RBAC](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/routers/orgs.py): `src/routers/orgs.py`
- [Organization storage](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/store/orgs.py): `src/store/orgs.py`

### Billing and platform

- [Invoice search API](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/routers/search.py): `src/routers/search.py`
- [Vector search](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/search/vector_store.py): `src/search/vector_store.py`
- [Billing API](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/routers/billing.py): `src/routers/billing.py`
- [Payment provider](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/billing/provider.py): `src/billing/provider.py`
- [Billing repository](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/billing/repository.py): `src/billing/repository.py`
- [Prometheus metrics](https://github.com/khanh02-vin/ai-invoice-billing/blob/main/src/observability/metrics.py): `src/observability/metrics.py`

### Other components

- **Invoice user**

## Connections

- Invoice user → React application: uses (evidence: `README.md`)
- React application → Invoice dashboard: renders (evidence: `frontend/src/App.jsx`)
- Invoice dashboard → API client: calls (evidence: `frontend/src/Invoices.jsx`)
- React application → API client: checks session (evidence: `frontend/src/App.jsx`)
- API client → FastAPI application: HTTP requests (evidence: `README.md`)
- FastAPI application → JWT security: verifies tokens (evidence: `src/app.py`)
- FastAPI application → User repository: resolves user (evidence: `src/app.py`)
- FastAPI application → Upload validation: validates upload (evidence: `src/app.py`)
- FastAPI application → Invoice extraction: extracts fields (evidence: `README.md`)
- Invoice extraction → LLM fallback: fallback extraction (evidence: `src/extract/extractor.py`)
- FastAPI application → Invoice domain: validates records (evidence: `src/app.py`)
- FastAPI application → Invoice repository: stores and queries (evidence: `src/app.py`)
- Invoice repository → SQLite database: persists invoices (evidence: `src/store/repository.py`)
- FastAPI application → Original file storage: stores uploads (evidence: `src/app.py`)
- FastAPI application → PDF reports: exports reports (evidence: `src/app.py`)
- Auth hardening → JWT security: uses token helpers (evidence: `src/routers/auth_ext.py`)
- Auth hardening → User repository: updates credentials (evidence: `src/routers/auth_ext.py`)
- Organizations and RBAC → Organization storage: reads and writes (evidence: `src/routers/orgs.py`)
- Invoice search API → JWT security: verifies tokens (evidence: `src/routers/search.py`)
- Invoice search API → Invoice repository: loads invoices (evidence: `src/routers/search.py`)
- Invoice search API → Vector search: queries index (evidence: `src/routers/search.py`)
- Billing API → Payment provider: dispatches payments (evidence: `src/routers/billing.py`)
- Billing API → Billing repository: persists billing (evidence: `src/routers/billing.py`)
- FastAPI application → Prometheus metrics: serves metrics (evidence: `src/app.py`)
