# asimansari-git/billprods-ai architecture

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

- Interactive diagram: https://gitdiagram.com/asimansari-git/billprods-ai
- Repository: https://github.com/asimansari-git/billprods-ai

## Overview

BillProds AI is a bill and product tracker with receipt scanning and a financial assistant. The primary workflow is: a user submits receipt files through the PWA, the frontend sends them to the API for AI processing, and bills and extracted products are stored for later viewing and analysis. Separate capabilities cover authentication, categories, notifications, subscriptions, and backup import/export. The graph follows sampled calls and documented architecture; several backend router-to-service links and unsampled feature internals are not shown because their wiring could not be verified.

Main entry points: [`backend/app/routers`](https://github.com/asimansari-git/billprods-ai/tree/main/backend/app/routers) (API routers), [`backend/app/core/database.py`](https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/core/database.py) (Database session), [`frontend/App.tsx`](https://github.com/asimansari-git/billprods-ai/blob/main/frontend/App.tsx) (App shell), [`frontend/services/apiService.ts`](https://github.com/asimansari-git/billprods-ai/blob/main/frontend/services/apiService.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["PWA client"]
  node_app["App shell<br/>[App.tsx]"]
  node_views["Main views"]
  node_authctx["Auth context<br/>[AuthContext.tsx]"]
  node_billmodal["Receipt intake<br/>[AddBillModal.tsx]"]
  node_share["Share target<br/>[useShareTarget.ts]"]
  node_sw["PWA worker<br/>[service-worker.js]"]
  node_api_client["API client<br/>[apiService.ts]"]
  node_category_ui["Category editor"]
  node_poller["Notification poller"]
end

subgraph group_api["Backend API"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_routers["API routers"]
end

subgraph group_domain["Domain services"]
  node_auth_service["Authentication<br/>[auth_service.py]"]
  node_bill_service["Bill operations<br/>[bill_service.py]"]
  node_ai_service["AI processing<br/>[ai_service.py]"]
  node_product_service["Product management<br/>[product_service.py]"]
  node_category_service["Category rules"]
  node_chat_service["Assistant tools"]
  node_billing_service["Subscriptions<br/>[billing_service.py]"]
end

subgraph group_state["Persistence and integrations"]
  node_models["Domain models"]
  node_database["Database session<br/>[database.py]"]
  node_postgres[("PostgreSQL")]
  node_email["Email service<br/>[email_service.py]"]
end

node_user(("User"))
node_gemini{{"Google Gemini"}}

node_user -->|"uses"| node_app
node_app -->|"checks session"| node_authctx
node_app -->|"renders"| node_views
node_app -->|"opens intake"| node_billmodal
node_user -->|"shares files"| node_sw
node_sw -->|"signals and caches"| node_share
node_share -->|"delivers files"| node_app
node_billmodal -->|"submits scans"| node_api_client
node_views -->|"requests data"| node_api_client
node_category_ui -->|"updates categories"| node_api_client
node_poller -->|"polls notices"| node_api_client
node_api_client -->|"sends requests"| node_fastapi
node_fastapi -->|"dispatches"| node_routers
node_routers -->|"authentication"| node_auth_service
node_routers -->|"bill operations"| node_bill_service
node_routers -->|"scan requests"| node_ai_service
node_routers -->|"product requests"| node_product_service
node_routers -->|"category requests"| node_category_service
node_routers -->|"assistant requests"| node_chat_service
node_routers -->|"subscription requests"| node_billing_service
node_bill_service -->|"queries and writes"| node_database
node_database -->|"persists"| node_postgres
node_bill_service -->|"uses entities"| node_models
node_auth_service -->|"reads and writes"| node_models
node_auth_service -->|"sends verification"| node_email
node_ai_service -.->|"extracts receipt data"| node_gemini
node_product_service -->|"manages products"| node_database
node_category_service -->|"stores rules"| node_database
node_chat_service -->|"accesses user data"| node_database
node_billing_service -->|"updates subscription"| node_database

click node_app "https://github.com/asimansari-git/billprods-ai/blob/main/frontend/App.tsx"
click node_views "https://github.com/asimansari-git/billprods-ai/tree/main/frontend/views"
click node_authctx "https://github.com/asimansari-git/billprods-ai/blob/main/frontend/contexts/AuthContext.tsx"
click node_billmodal "https://github.com/asimansari-git/billprods-ai/blob/main/frontend/components/AddBillModal.tsx"
click node_share "https://github.com/asimansari-git/billprods-ai/blob/main/frontend/hooks/useShareTarget.ts"
click node_sw "https://github.com/asimansari-git/billprods-ai/blob/main/frontend/public/service-worker.js"
click node_api_client "https://github.com/asimansari-git/billprods-ai/blob/main/frontend/services/apiService.ts"
click node_category_ui "https://github.com/asimansari-git/billprods-ai/blob/main/frontend/components/CategoryManagerModal.tsx"
click node_poller "https://github.com/asimansari-git/billprods-ai/blob/main/frontend/components/NotificationPoller.tsx"
click node_fastapi "https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/main.py"
click node_routers "https://github.com/asimansari-git/billprods-ai/tree/main/backend/app/routers"
click node_auth_service "https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/auth_service.py"
click node_bill_service "https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/bill_service.py"
click node_ai_service "https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/ai_service.py"
click node_product_service "https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/product_service.py"
click node_category_service "https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/category_service.py"
click node_chat_service "https://github.com/asimansari-git/billprods-ai/tree/main/backend/app/services/chat_tools"
click node_billing_service "https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/billing_service.py"
click node_models "https://github.com/asimansari-git/billprods-ai/tree/main/backend/app/models"
click node_database "https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/core/database.py"
click node_email "https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/email_service.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_app,node_views,node_authctx,node_billmodal,node_share,node_sw,node_api_client,node_category_ui,node_poller,node_user toneBlue
class node_fastapi,node_routers toneAmber
class node_auth_service,node_bill_service,node_ai_service,node_product_service,node_category_service,node_chat_service,node_billing_service toneMint
class node_models,node_database,node_postgres,node_email toneRose
class node_gemini toneIndigo
```

## Components

### PWA client

- [App shell](https://github.com/asimansari-git/billprods-ai/blob/main/frontend/App.tsx): `frontend/App.tsx`
- [Main views](https://github.com/asimansari-git/billprods-ai/tree/main/frontend/views): `frontend/views`
- [Auth context](https://github.com/asimansari-git/billprods-ai/blob/main/frontend/contexts/AuthContext.tsx): `frontend/contexts/AuthContext.tsx`
- [Receipt intake](https://github.com/asimansari-git/billprods-ai/blob/main/frontend/components/AddBillModal.tsx): `frontend/components/AddBillModal.tsx`
- [Share target](https://github.com/asimansari-git/billprods-ai/blob/main/frontend/hooks/useShareTarget.ts): `frontend/hooks/useShareTarget.ts`
- [PWA worker](https://github.com/asimansari-git/billprods-ai/blob/main/frontend/public/service-worker.js): `frontend/public/service-worker.js`
- [API client](https://github.com/asimansari-git/billprods-ai/blob/main/frontend/services/apiService.ts): `frontend/services/apiService.ts`
- [Category editor](https://github.com/asimansari-git/billprods-ai/blob/main/frontend/components/CategoryManagerModal.tsx): `frontend/components/CategoryManagerModal.tsx`
- [Notification poller](https://github.com/asimansari-git/billprods-ai/blob/main/frontend/components/NotificationPoller.tsx): `frontend/components/NotificationPoller.tsx`

### Backend API

- [FastAPI app](https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routers](https://github.com/asimansari-git/billprods-ai/tree/main/backend/app/routers): `backend/app/routers`

### Domain services

- [Authentication](https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Bill operations](https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/bill_service.py): `backend/app/services/bill_service.py`
- [AI processing](https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [Product management](https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/product_service.py): `backend/app/services/product_service.py`
- [Category rules](https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/category_service.py): `backend/app/services/category_service.py`
- [Assistant tools](https://github.com/asimansari-git/billprods-ai/tree/main/backend/app/services/chat_tools): `backend/app/services/chat_tools`
- [Subscriptions](https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/billing_service.py): `backend/app/services/billing_service.py`

### Persistence and integrations

- [Domain models](https://github.com/asimansari-git/billprods-ai/tree/main/backend/app/models): `backend/app/models`
- [Database session](https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- **PostgreSQL**
- [Email service](https://github.com/asimansari-git/billprods-ai/blob/main/backend/app/services/email_service.py): `backend/app/services/email_service.py`

### Other components

- **User**
- **Google Gemini**

## Connections

- User → App shell: uses
- App shell → Auth context: checks session
- App shell → Main views: renders
- App shell → Receipt intake: opens intake
- User → PWA worker: shares files
- PWA worker → Share target: signals and caches
- Share target → App shell: delivers files
- Receipt intake → API client: submits scans
- Main views → API client: requests data
- Category editor → API client: updates categories
- Notification poller → API client: polls notices
- API client → FastAPI app: sends requests
- FastAPI app → API routers: dispatches
- API routers → Authentication: authentication
- API routers → Bill operations: bill operations
- API routers → AI processing: scan requests
- API routers → Product management: product requests
- API routers → Category rules: category requests
- API routers → Assistant tools: assistant requests
- API routers → Subscriptions: subscription requests
- Bill operations → Database session: queries and writes
- Database session → PostgreSQL: persists
- Bill operations → Domain models: uses entities
- Authentication → Domain models: reads and writes
- Authentication → Email service: sends verification
- AI processing → Google Gemini: extracts receipt data
- Product management → Database session: manages products
- Category rules → Database session: stores rules
- Assistant tools → Database session: accesses user data
- Subscriptions → Database session: updates subscription