# arsalanfarooq12/finance-agent architecture

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

- Interactive diagram: https://gitdiagram.com/arsalanfarooq12/finance-agent
- Repository: https://github.com/arsalanfarooq12/finance-agent

## Overview

FinanceAI is a personal-finance web app: users authenticate, then track expenses via chat or PDF statements, manage budgets, and review spending in a dashboard. The frontend calls an authenticated Express API; chat requests enter a LangGraph orchestrator that routes to expense, budget, advice, or general responses. Supabase provides authentication and persistent user data, while Google Gemini powers chat and documented embeddings. The graph follows the documented product capabilities and sampled call sites; unsampled upload and advice details are represented only where the README or source index supports them.

Main entry points: [`backend/src/db/database.ts`](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/db/database.ts) (Data access), [`backend/src/index.ts`](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/index.ts) (Express server), [`backend/src/agent/orchestrator.ts`](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/orchestrator.ts) (Intent orchestrator), [`frontend/src/api.ts`](https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_landing["Landing page<br/>[LandingPage.tsx]"]
  node_authpage["Sign-in and registration<br/>[AuthPage.tsx]"]
  node_authctx["Auth session<br/>[AuthContext.tsx]"]
  node_app["Workspace shell<br/>[App.tsx]"]
  node_chatui["Streaming chat<br/>[Chat.tsx]"]
  node_dashboard["Spending dashboard<br/>[Dashboard.tsx]"]
  node_budgetui["Budget panel<br/>[BudgetPanel.tsx]"]
  node_uploadui["Statement upload<br/>[PDFUpload.tsx]"]
  node_uploadwrap["Upload wrapper"]
  node_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and security"]
  node_server["Express server<br/>[index.ts]"]
  node_authmw["JWT verification<br/>[verifyToken.ts]"]
  node_chatroute["Chat endpoints<br/>[chat.ts]"]
  node_expensesroute["Expense endpoints<br/>[expenses.ts]"]
  node_budgetroute["Budget endpoints<br/>[budget.ts]"]
  node_uploadroute["PDF processing<br/>[upload.ts]"]
end

subgraph group_agent["Finance agent"]
  node_orchestrator["Intent orchestrator<br/>[orchestrator.ts]"]
  node_expenseagent["Expense agent<br/>[expenseAgent.ts]"]
  node_budgetagent["Budget agent<br/>[budgetAgent.ts]"]
  node_adviceagent["Advice agent<br/>[adviceAgent.ts]"]
  node_budgettools["Budget status logic<br/>[budgetTools.ts]"]
  node_llm["Model fallback<br/>[llm.ts]"]
  node_knowledge["Financial knowledge base<br/>[knowledgeBase.ts]"]
end

subgraph group_data["Persistence and AI"]
  node_dbaccess["Data access<br/>[database.ts]"]
  node_supabaseclient["Supabase service client<br/>[supabase.ts]"]
end

node_user(("Finance user"))
node_supabaseauth{{"Supabase Auth"}}
node_postgres[("Supabase database")]
node_google{{"Google Gemini"}}

node_user -->|"opens"| node_landing
node_user -->|"signs in"| node_authpage
node_authpage -->|"requests auth"| node_authctx
node_authctx -->|"authenticates"| node_supabaseauth
node_app -->|"checks session"| node_authctx
node_app -->|"renders"| node_chatui
node_app -->|"renders"| node_dashboard
node_dashboard -->|"loads and edits"| node_client
node_dashboard -->|"renders"| node_budgetui
node_dashboard -->|"renders"| node_uploadwrap
node_uploadwrap -->|"renders"| node_uploadui
node_uploadui -->|"uploads statement"| node_client
node_budgetui -->|"manages budgets"| node_client
node_chatui -->|"streams messages"| node_client
node_client -->|"calls API"| node_server
node_server -->|"routes chat"| node_chatroute
node_server -->|"routes expenses"| node_expensesroute
node_server -->|"routes budgets"| node_budgetroute
node_server -->|"routes uploads"| node_uploadroute
node_server -->|"guards API"| node_authmw
node_authmw -->|"verifies token"| node_supabaseauth
node_chatroute -->|"runs agent"| node_orchestrator
node_expensesroute -->|"reads and writes"| node_dbaccess
node_budgetroute -->|"reads and writes"| node_dbaccess
node_orchestrator -->|"dispatches"| node_expenseagent
node_orchestrator -->|"dispatches"| node_budgetagent
node_orchestrator -->|"dispatches"| node_adviceagent
node_orchestrator -->|"classifies and answers"| node_llm
node_orchestrator -->|"loads and saves history"| node_dbaccess
node_expenseagent -->|"manages expenses"| node_dbaccess
node_expenseagent -->|"checks budgets"| node_budgettools
node_budgetagent -->|"manages budgets"| node_dbaccess
node_adviceagent -.->|"uses guidance"| node_knowledge
node_adviceagent -->|"generates advice"| node_llm
node_expenseagent -->|"calls model"| node_llm
node_budgetagent -->|"calls model"| node_llm
node_dbaccess -->|"queries through"| node_supabaseclient
node_supabaseclient -.->|"connects to"| node_postgres
node_llm -.->|"invokes models"| node_google
node_knowledge -.->|"embeds documents"| node_google
node_client -->|"gets access token"| node_supabaseauth
node_uploadroute -.->|"saves extracted expenses"| node_dbaccess

click node_landing "https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/pages/LandingPage.tsx"
click node_authpage "https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/pages/AuthPage.tsx"
click node_authctx "https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_app "https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/App.tsx"
click node_chatui "https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/components/Chat.tsx"
click node_dashboard "https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/components/Dashboard.tsx"
click node_budgetui "https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/components/BudgetPanel.tsx"
click node_uploadui "https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/components/PDFUpload.tsx"
click node_uploadwrap "https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/components/UploadStatement.tsx"
click node_client "https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/api.ts"
click node_server "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/index.ts"
click node_authmw "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/middleware/verifyToken.ts"
click node_chatroute "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/routes/chat.ts"
click node_expensesroute "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/routes/expenses.ts"
click node_budgetroute "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/routes/budget.ts"
click node_uploadroute "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/routes/upload.ts"
click node_orchestrator "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/orchestrator.ts"
click node_expenseagent "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/subgraphs/expenseAgent.ts"
click node_budgetagent "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/subgraphs/budgetAgent.ts"
click node_adviceagent "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/subgraphs/adviceAgent.ts"
click node_budgettools "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/budgetTools.ts"
click node_llm "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/llm.ts"
click node_knowledge "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/knowledgeBase.ts"
click node_dbaccess "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/db/database.ts"
click node_supabaseclient "https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/lib/supabase.ts"

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_authpage,node_authctx,node_app,node_chatui,node_dashboard,node_budgetui,node_uploadui,node_uploadwrap,node_client,node_user toneBlue
class node_server,node_authmw,node_chatroute,node_expensesroute,node_budgetroute,node_uploadroute,node_postgres toneAmber
class node_orchestrator,node_expenseagent,node_budgetagent,node_adviceagent,node_budgettools,node_llm,node_knowledge toneMint
class node_dbaccess,node_supabaseclient toneRose
class node_supabaseauth,node_google toneIndigo
```

## Components

### User interface

- [Landing page](https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/pages/LandingPage.tsx): `frontend/src/pages/LandingPage.tsx`
- [Sign-in and registration](https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/pages/AuthPage.tsx): `frontend/src/pages/AuthPage.tsx`
- [Auth session](https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/contexts/AuthContext.tsx): `frontend/src/contexts/AuthContext.tsx`
- [Workspace shell](https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Streaming chat](https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/components/Chat.tsx): `frontend/src/components/Chat.tsx`
- [Spending dashboard](https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/components/Dashboard.tsx): `frontend/src/components/Dashboard.tsx`
- [Budget panel](https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/components/BudgetPanel.tsx): `frontend/src/components/BudgetPanel.tsx`
- [Statement upload](https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/components/PDFUpload.tsx): `frontend/src/components/PDFUpload.tsx`
- [Upload wrapper](https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/components/UploadStatement.tsx): `frontend/src/components/UploadStatement.tsx`
- [API client](https://github.com/arsalanfarooq12/finance-agent/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### API and security

- [Express server](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [JWT verification](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/middleware/verifyToken.ts): `backend/src/middleware/verifyToken.ts`
- [Chat endpoints](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/routes/chat.ts): `backend/src/routes/chat.ts`
- [Expense endpoints](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/routes/expenses.ts): `backend/src/routes/expenses.ts`
- [Budget endpoints](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/routes/budget.ts): `backend/src/routes/budget.ts`
- [PDF processing](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/routes/upload.ts): `backend/src/routes/upload.ts`

### Finance agent

- [Intent orchestrator](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/orchestrator.ts): `backend/src/agent/orchestrator.ts`
- [Expense agent](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/subgraphs/expenseAgent.ts): `backend/src/agent/subgraphs/expenseAgent.ts`
- [Budget agent](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/subgraphs/budgetAgent.ts): `backend/src/agent/subgraphs/budgetAgent.ts`
- [Advice agent](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/subgraphs/adviceAgent.ts): `backend/src/agent/subgraphs/adviceAgent.ts`
- [Budget status logic](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/budgetTools.ts): `backend/src/agent/budgetTools.ts`
- [Model fallback](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/llm.ts): `backend/src/agent/llm.ts`
- [Financial knowledge base](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/agent/knowledgeBase.ts): `backend/src/agent/knowledgeBase.ts`

### Persistence and AI

- [Data access](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/db/database.ts): `backend/src/db/database.ts`
- [Supabase service client](https://github.com/arsalanfarooq12/finance-agent/blob/main/backend/src/lib/supabase.ts): `backend/src/lib/supabase.ts`

### Other components

- **Finance user**
- **Supabase Auth**
- **Supabase database**
- **Google Gemini**

## Connections

- Finance user → Landing page: opens
- Finance user → Sign-in and registration: signs in (evidence: `frontend/src/pages/AuthPage.tsx`)
- Sign-in and registration → Auth session: requests auth (evidence: `frontend/src/pages/AuthPage.tsx`)
- Auth session → Supabase Auth: authenticates (evidence: `frontend/src/contexts/AuthContext.tsx`)
- Workspace shell → Auth session: checks session (evidence: `frontend/src/App.tsx`)
- Workspace shell → Streaming chat: renders (evidence: `frontend/src/App.tsx`)
- Workspace shell → Spending dashboard: renders (evidence: `frontend/src/App.tsx`)
- Spending dashboard → API client: loads and edits (evidence: `frontend/src/components/Dashboard.tsx`)
- Spending dashboard → Budget panel: renders (evidence: `frontend/src/components/Dashboard.tsx`)
- Spending dashboard → Upload wrapper: renders (evidence: `frontend/src/components/Dashboard.tsx`)
- Upload wrapper → Statement upload: renders (evidence: `frontend/src/components/UploadStatement.tsx`)
- Statement upload → API client: uploads statement (evidence: `frontend/src/components/PDFUpload.tsx`)
- Budget panel → API client: manages budgets (evidence: `frontend/src/components/BudgetPanel.tsx`)
- Streaming chat → API client: streams messages (evidence: `frontend/src/components/Chat.tsx`)
- API client → Express server: calls API (evidence: `frontend/src/api.ts`)
- Express server → Chat endpoints: routes chat (evidence: `backend/src/index.ts`)
- Express server → Expense endpoints: routes expenses (evidence: `backend/src/index.ts`)
- Express server → Budget endpoints: routes budgets (evidence: `backend/src/index.ts`)
- Express server → PDF processing: routes uploads (evidence: `backend/src/index.ts`)
- Express server → JWT verification: guards API (evidence: `backend/src/index.ts`)
- JWT verification → Supabase Auth: verifies token (evidence: `backend/src/middleware/verifyToken.ts`)
- Chat endpoints → Intent orchestrator: runs agent (evidence: `backend/src/routes/chat.ts`)
- Expense endpoints → Data access: reads and writes (evidence: `backend/src/routes/expenses.ts`)
- Budget endpoints → Data access: reads and writes (evidence: `backend/src/routes/budget.ts`)
- Intent orchestrator → Expense agent: dispatches (evidence: `backend/src/agent/orchestrator.ts`)
- Intent orchestrator → Budget agent: dispatches (evidence: `backend/src/agent/orchestrator.ts`)
- Intent orchestrator → Advice agent: dispatches (evidence: `backend/src/agent/orchestrator.ts`)
- Intent orchestrator → Model fallback: classifies and answers (evidence: `backend/src/agent/orchestrator.ts`)
- Intent orchestrator → Data access: loads and saves history (evidence: `backend/src/agent/orchestrator.ts`)
- Expense agent → Data access: manages expenses (evidence: `backend/src/agent/subgraphs/expenseAgent.ts`)
- Expense agent → Budget status logic: checks budgets (evidence: `backend/src/agent/subgraphs/expenseAgent.ts`)
- Budget agent → Data access: manages budgets (evidence: `backend/src/agent/subgraphs/budgetAgent.ts`)
- Advice agent → Financial knowledge base: uses guidance (evidence: `backend/src/agent/subgraphs/adviceAgent.ts`)
- Advice agent → Model fallback: generates advice (evidence: `backend/src/agent/subgraphs/adviceAgent.ts`)
- Expense agent → Model fallback: calls model (evidence: `backend/src/agent/subgraphs/expenseAgent.ts`)
- Budget agent → Model fallback: calls model (evidence: `backend/src/agent/subgraphs/budgetAgent.ts`)
- Data access → Supabase service client: queries through (evidence: `backend/src/db/database.ts`)
- Supabase service client → Supabase database: connects to
- Model fallback → Google Gemini: invokes models
- Financial knowledge base → Google Gemini: embeds documents
- API client → Supabase Auth: gets access token (evidence: `frontend/src/api.ts`)
- PDF processing → Data access: saves extracted expenses
