# ashwarygupta/invox architecture

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

- Interactive diagram: https://gitdiagram.com/ashwarygupta/invox
- Repository: https://github.com/ashwarygupta/invox

## Overview

Invox is an invoice-management product spanning a Next.js interface and FastAPI services. Users authenticate, import invoices by upload or connected email, review and manage extracted records, and query them through dashboard analytics or natural-language chat. The README documents Gemini-based extraction, Gmail/IMAP polling, exports, and approval automation; sampled code directly confirms the hybrid chat routing, OAuth handoff, API client behavior, and persistence setup. Several endpoint and processing implementations were not sampled, so their internal wiring is represented only at the documented subsystem level.

Main entry points: [`backend/app/main.py`](https://github.com/ashwarygupta/invox/blob/main/backend/app/main.py) (FastAPI app), [`lib/api/client.ts`](https://github.com/ashwarygupta/invox/blob/main/lib/api/client.ts) (API client), [`app/layout.tsx`](https://github.com/ashwarygupta/invox/blob/main/app/layout.tsx) (Next.js app), [`backend/app/services/hybrid_query_engine.py`](https://github.com/ashwarygupta/invox/blob/main/backend/app/services/hybrid_query_engine.py) (Query router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web app"]
  node_web["Next.js app<br/>[layout.tsx]"]
  node_dashboard["Dashboard"]
  node_upload_ui["Invoice upload<br/>[FileUploader.tsx]"]
  node_chat_ui["Invoice chat<br/>[ChatInterface.tsx]"]
  node_gmail_ui["Gmail connect"]
  node_auth_front["Google sign-in<br/>[route.ts]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["Backend API"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_auth_endpoint["Auth endpoints<br/>[auth.py]"]
  node_invoice_endpoint["Invoice endpoints<br/>[invoices.py]"]
  node_chat_endpoint["Chat endpoint<br/>[chat.py]"]
  node_email_endpoint["Email config<br/>[email_config.py]"]
  node_gmail_endpoint["Gmail OAuth<br/>[gmail_oauth.py]"]
end

subgraph group_services["Invoice services"]
  node_processing["Invoice extraction"]
  node_hybrid["Query router"]
  node_classifier["Query classifier"]
  node_sql_agent["SQL agent<br/>[sql_agent.py]"]
  node_rag["Semantic search<br/>[rag_system.py]"]
  node_email_poller["Email polling<br/>[email_polling.py]"]
  node_worker["Polling worker<br/>[email_poller.py]"]
end

subgraph group_state["Data and integrations"]
  node_database[("Relational database<br/>[session.py]")]
  node_semantic_store[("ChromaDB index<br/>[rag_system.py]")]
end

node_user(("Invoice user"))
node_google{{"Google OAuth"}}
node_gmail{{"Gmail API / IMAP"}}
node_gemini{{"Gemini AI"}}
node_openrouter{{"OpenRouter LLM"}}

node_user -->|"uses"| node_web
node_web -->|"opens"| node_dashboard
node_web -->|"opens"| node_upload_ui
node_web -->|"opens"| node_chat_ui
node_web -->|"opens"| node_gmail_ui
node_user -->|"signs in"| node_auth_front
node_auth_front -->|"authenticates"| node_google
node_auth_front -->|"posts OAuth data"| node_auth_endpoint
node_dashboard -->|"requests data"| node_api_client
node_upload_ui -->|"uploads file"| node_api_client
node_chat_ui -->|"sends query"| node_api_client
node_gmail_ui -->|"requests OAuth"| node_api_client
node_api_client -->|"calls API"| node_api_app
node_api_app -->|"dispatches"| node_auth_endpoint
node_api_app -->|"dispatches"| node_invoice_endpoint
node_api_app -->|"dispatches"| node_chat_endpoint
node_api_app -->|"dispatches"| node_email_endpoint
node_api_app -->|"dispatches"| node_gmail_endpoint
node_invoice_endpoint -->|"processes invoice"| node_processing
node_processing -.->|"extracts fields"| node_gemini
node_invoice_endpoint -->|"reads and writes"| node_database
node_processing -->|"stores extracted data"| node_database
node_dashboard -->|"loads analytics"| node_api_client
node_chat_endpoint -->|"queries"| node_hybrid
node_hybrid -->|"classifies query"| node_classifier
node_hybrid -->|"runs analytics"| node_sql_agent
node_hybrid -->|"runs semantic search"| node_rag
node_sql_agent -->|"queries invoices"| node_database
node_rag -->|"searches index"| node_semantic_store
node_rag -->|"loads invoices"| node_database
node_hybrid -.->|"synthesizes answer"| node_openrouter
node_gmail_ui -->|"connects account"| node_gmail_endpoint
node_gmail_endpoint -->|"exchanges OAuth code"| node_gmail
node_gmail_endpoint -->|"stores credentials"| node_database
node_email_endpoint -->|"triggers polling"| node_email_poller
node_worker -->|"runs polling"| node_email_poller
node_email_poller -.->|"checks mail"| node_gmail
node_email_poller -->|"submits invoices"| node_processing

click node_web "https://github.com/ashwarygupta/invox/blob/main/app/layout.tsx"
click node_dashboard "https://github.com/ashwarygupta/invox/blob/main/app/dashboard/DashboardContent.tsx"
click node_upload_ui "https://github.com/ashwarygupta/invox/blob/main/components/FileUploader.tsx"
click node_chat_ui "https://github.com/ashwarygupta/invox/blob/main/components/ChatInterface.tsx"
click node_gmail_ui "https://github.com/ashwarygupta/invox/blob/main/components/GmailOAuthButton.tsx"
click node_auth_front "https://github.com/ashwarygupta/invox/blob/main/app/api/auth/%5B...nextauth%5D/route.ts"
click node_api_client "https://github.com/ashwarygupta/invox/blob/main/lib/api/client.ts"
click node_api_app "https://github.com/ashwarygupta/invox/blob/main/backend/app/main.py"
click node_auth_endpoint "https://github.com/ashwarygupta/invox/blob/main/backend/app/api/v1/endpoints/auth.py"
click node_invoice_endpoint "https://github.com/ashwarygupta/invox/blob/main/backend/app/api/v1/endpoints/invoices.py"
click node_chat_endpoint "https://github.com/ashwarygupta/invox/blob/main/backend/app/api/v1/endpoints/chat.py"
click node_email_endpoint "https://github.com/ashwarygupta/invox/blob/main/backend/app/api/v1/endpoints/email_config.py"
click node_gmail_endpoint "https://github.com/ashwarygupta/invox/blob/main/backend/app/api/v1/endpoints/gmail_oauth.py"
click node_processing "https://github.com/ashwarygupta/invox/blob/main/backend/app/services/invoice_processing.py"
click node_hybrid "https://github.com/ashwarygupta/invox/blob/main/backend/app/services/hybrid_query_engine.py"
click node_classifier "https://github.com/ashwarygupta/invox/blob/main/backend/app/services/query_classifier.py"
click node_sql_agent "https://github.com/ashwarygupta/invox/blob/main/backend/app/services/sql_agent.py"
click node_rag "https://github.com/ashwarygupta/invox/blob/main/backend/app/services/rag_system.py"
click node_email_poller "https://github.com/ashwarygupta/invox/blob/main/backend/app/services/email_polling.py"
click node_worker "https://github.com/ashwarygupta/invox/blob/main/backend/app/workers/email_poller.py"
click node_database "https://github.com/ashwarygupta/invox/blob/main/backend/app/db/session.py"
click node_semantic_store "https://github.com/ashwarygupta/invox/blob/main/backend/app/services/rag_system.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_dashboard,node_upload_ui,node_chat_ui,node_gmail_ui,node_auth_front,node_api_client,node_user toneBlue
class node_api_app,node_auth_endpoint,node_invoice_endpoint,node_chat_endpoint,node_email_endpoint,node_gmail_endpoint toneAmber
class node_processing,node_hybrid,node_classifier,node_sql_agent,node_rag,node_email_poller,node_worker,node_gmail,node_openrouter toneMint
class node_database,node_semantic_store toneRose
class node_google,node_gemini toneIndigo
```

## Components

### Web app

- [Next.js app](https://github.com/ashwarygupta/invox/blob/main/app/layout.tsx): `app/layout.tsx`
- [Dashboard](https://github.com/ashwarygupta/invox/blob/main/app/dashboard/DashboardContent.tsx): `app/dashboard/DashboardContent.tsx`
- [Invoice upload](https://github.com/ashwarygupta/invox/blob/main/components/FileUploader.tsx): `components/FileUploader.tsx`
- [Invoice chat](https://github.com/ashwarygupta/invox/blob/main/components/ChatInterface.tsx): `components/ChatInterface.tsx`
- [Gmail connect](https://github.com/ashwarygupta/invox/blob/main/components/GmailOAuthButton.tsx): `components/GmailOAuthButton.tsx`
- [Google sign-in](https://github.com/ashwarygupta/invox/blob/main/app/api/auth/%5B...nextauth%5D/route.ts): `app/api/auth/[...nextauth]/route.ts`
- [API client](https://github.com/ashwarygupta/invox/blob/main/lib/api/client.ts): `lib/api/client.ts`

### Backend API

- [FastAPI app](https://github.com/ashwarygupta/invox/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth endpoints](https://github.com/ashwarygupta/invox/blob/main/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`
- [Invoice endpoints](https://github.com/ashwarygupta/invox/blob/main/backend/app/api/v1/endpoints/invoices.py): `backend/app/api/v1/endpoints/invoices.py`
- [Chat endpoint](https://github.com/ashwarygupta/invox/blob/main/backend/app/api/v1/endpoints/chat.py): `backend/app/api/v1/endpoints/chat.py`
- [Email config](https://github.com/ashwarygupta/invox/blob/main/backend/app/api/v1/endpoints/email_config.py): `backend/app/api/v1/endpoints/email_config.py`
- [Gmail OAuth](https://github.com/ashwarygupta/invox/blob/main/backend/app/api/v1/endpoints/gmail_oauth.py): `backend/app/api/v1/endpoints/gmail_oauth.py`

### Invoice services

- [Invoice extraction](https://github.com/ashwarygupta/invox/blob/main/backend/app/services/invoice_processing.py): `backend/app/services/invoice_processing.py`
- [Query router](https://github.com/ashwarygupta/invox/blob/main/backend/app/services/hybrid_query_engine.py): `backend/app/services/hybrid_query_engine.py`
- [Query classifier](https://github.com/ashwarygupta/invox/blob/main/backend/app/services/query_classifier.py): `backend/app/services/query_classifier.py`
- [SQL agent](https://github.com/ashwarygupta/invox/blob/main/backend/app/services/sql_agent.py): `backend/app/services/sql_agent.py`
- [Semantic search](https://github.com/ashwarygupta/invox/blob/main/backend/app/services/rag_system.py): `backend/app/services/rag_system.py`
- [Email polling](https://github.com/ashwarygupta/invox/blob/main/backend/app/services/email_polling.py): `backend/app/services/email_polling.py`
- [Polling worker](https://github.com/ashwarygupta/invox/blob/main/backend/app/workers/email_poller.py): `backend/app/workers/email_poller.py`

### Data and integrations

- [Relational database](https://github.com/ashwarygupta/invox/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [ChromaDB index](https://github.com/ashwarygupta/invox/blob/main/backend/app/services/rag_system.py): `backend/app/services/rag_system.py`

### Other components

- **Invoice user**
- **Google OAuth**
- **Gmail API / IMAP**
- **Gemini AI**
- **OpenRouter LLM**

## Connections

- Invoice user → Next.js app: uses
- Next.js app → Dashboard: opens
- Next.js app → Invoice upload: opens
- Next.js app → Invoice chat: opens
- Next.js app → Gmail connect: opens
- Invoice user → Google sign-in: signs in
- Google sign-in → Google OAuth: authenticates
- Google sign-in → Auth endpoints: posts OAuth data
- Dashboard → API client: requests data
- Invoice upload → API client: uploads file
- Invoice chat → API client: sends query
- Gmail connect → API client: requests OAuth
- API client → FastAPI app: calls API
- FastAPI app → Auth endpoints: dispatches
- FastAPI app → Invoice endpoints: dispatches
- FastAPI app → Chat endpoint: dispatches
- FastAPI app → Email config: dispatches
- FastAPI app → Gmail OAuth: dispatches
- Invoice endpoints → Invoice extraction: processes invoice
- Invoice extraction → Gemini AI: extracts fields
- Invoice endpoints → Relational database: reads and writes
- Invoice extraction → Relational database: stores extracted data
- Dashboard → API client: loads analytics
- Chat endpoint → Query router: queries
- Query router → Query classifier: classifies query
- Query router → SQL agent: runs analytics
- Query router → Semantic search: runs semantic search
- SQL agent → Relational database: queries invoices
- Semantic search → ChromaDB index: searches index
- Semantic search → Relational database: loads invoices
- Query router → OpenRouter LLM: synthesizes answer
- Gmail connect → Gmail OAuth: connects account
- Gmail OAuth → Gmail API / IMAP: exchanges OAuth code
- Gmail OAuth → Relational database: stores credentials
- Email config → Email polling: triggers polling
- Polling worker → Email polling: runs polling
- Email polling → Gmail API / IMAP: checks mail
- Email polling → Invoice extraction: submits invoices