# nihar8262/expense-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/nihar8262/expense-tracker
- Repository: https://github.com/nihar8262/expense-tracker

## Overview

Expense Tracker is a full-stack personal finance app. A user signs in, works with expenses, budgets, wallets, loans, and reminders in the React client, and receives results through authenticated API calls backed by PostgreSQL. The graph follows the documented client/API/storage flow and preserves major product branches, including the assistant, receipt scanning, and MCP integrations. Some capability implementations are represented by their enclosing directories because their source was not sampled; edges without direct evidence are omitted.

Main entry points: [`backend/src/http.ts`](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/http.ts) (Request handlers), [`backend/src/app.ts`](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/app.ts) (Express application), [`frontend/src/App.tsx`](https://github.com/nihar8262/expense-tracker/blob/master/frontend/src/App.tsx) (React application), [`frontend/src/pages`](https://github.com/nihar8262/expense-tracker/tree/master/frontend/src/pages) (Finance workspaces)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_react["React application<br/>[App.tsx]"]
  node_authui["Sign-in and session<br/>[useAuth.ts]"]
  node_features["Finance workspaces"]
  node_clientapi["API client<br/>[api.ts]"]
end

subgraph group_api["Application API"]
  node_express["Express application<br/>[app.ts]"]
  node_handlers["Request handlers<br/>[http.ts]"]
  node_authserver["Server authentication<br/>[auth.ts]"]
end

subgraph group_finance["Finance capabilities"]
  node_expense["Personal expenses<br/>[http.ts]"]
  node_budgets["Budgets<br/>[http.ts]"]
  node_wallets["Shared wallets<br/>[http.ts]"]
  node_loans["Peer loans<br/>[http.ts]"]
  node_alerts["Notifications and bills<br/>[http.ts]"]
end

subgraph group_assist["Assistant integrations"]
  node_assistant["Finance assistant"]
  node_tools["Assistant tools<br/>[tools.ts]"]
  node_ocr["Receipt scanning<br/>[geminiOcr.ts]"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_token[("Personal access tokens<br/>[tokenStore.ts]")]
  node_embeddings["Semantic search embeddings"]
end

subgraph group_persistence["Persistence"]
  node_store[("PostgreSQL store<br/>[postgres.ts]")]
  node_database[("PostgreSQL")]
end

node_user(("Finance user"))
node_gemini["Gemini embeddings API"]

node_user -->|"uses"| node_react
node_react -->|"authenticates"| node_authui
node_react -->|"renders"| node_features
node_features -->|"requests data"| node_clientapi
node_clientapi -->|"calls API"| node_express
node_express -->|"authenticates requests"| node_authserver
node_express -->|"dispatches"| node_handlers
node_handlers -->|"handles"| node_expense
node_handlers -->|"handles"| node_budgets
node_handlers -->|"handles"| node_wallets
node_handlers -->|"handles"| node_loans
node_handlers -->|"handles"| node_alerts
node_handlers -->|"reads and writes"| node_store
node_store -->|"persists data"| node_database
node_express -->|"routes requests"| node_assistant
node_assistant -->|"executes tools"| node_tools
node_mcp -->|"dispatches tools"| node_tools
node_mcp -->|"authenticates tokens"| node_token
node_store -->|"saves embeddings"| node_embeddings
node_embeddings -->|"requests vectors"| node_gemini
node_features -->|"scans receipts"| node_ocr
node_user -.->|"connects external tools"| node_mcp

click node_react "https://github.com/nihar8262/expense-tracker/blob/master/frontend/src/App.tsx"
click node_authui "https://github.com/nihar8262/expense-tracker/blob/master/frontend/src/hooks/useAuth.ts"
click node_features "https://github.com/nihar8262/expense-tracker/tree/master/frontend/src/pages"
click node_clientapi "https://github.com/nihar8262/expense-tracker/blob/master/frontend/src/services/api.ts"
click node_express "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/app.ts"
click node_handlers "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/http.ts"
click node_authserver "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/auth.ts"
click node_expense "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/http.ts"
click node_budgets "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/http.ts"
click node_wallets "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/http.ts"
click node_loans "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/http.ts"
click node_alerts "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/http.ts"
click node_assistant "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/assistant/assistantService.ts"
click node_tools "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/assistant/tools.ts"
click node_ocr "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/mcp/geminiOcr.ts"
click node_mcp "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/mcp/server.ts"
click node_token "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/mcp/tokenStore.ts"
click node_store "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/store/postgres.ts"
click node_embeddings "https://github.com/nihar8262/expense-tracker/blob/master/backend/src/mcp/embeddingsHelper.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_react,node_authui,node_features,node_clientapi,node_user toneBlue
class node_express,node_handlers,node_authserver toneAmber
class node_expense,node_budgets,node_wallets,node_loans,node_alerts,node_gemini toneMint
class node_assistant,node_tools,node_ocr,node_mcp,node_token,node_embeddings toneRose
class node_store,node_database toneIndigo
```

## Components

### Web client

- [React application](https://github.com/nihar8262/expense-tracker/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sign-in and session](https://github.com/nihar8262/expense-tracker/blob/master/frontend/src/hooks/useAuth.ts): `frontend/src/hooks/useAuth.ts`
- [Finance workspaces](https://github.com/nihar8262/expense-tracker/tree/master/frontend/src/pages): `frontend/src/pages`
- [API client](https://github.com/nihar8262/expense-tracker/blob/master/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Application API

- [Express application](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/app.ts): `backend/src/app.ts`
- [Request handlers](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/http.ts): `backend/src/http.ts`
- [Server authentication](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/auth.ts): `backend/src/auth.ts`

### Finance capabilities

- [Personal expenses](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/http.ts): `backend/src/http.ts`
- [Budgets](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/http.ts): `backend/src/http.ts`
- [Shared wallets](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/http.ts): `backend/src/http.ts`
- [Peer loans](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/http.ts): `backend/src/http.ts`
- [Notifications and bills](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/http.ts): `backend/src/http.ts`

### Assistant integrations

- [Finance assistant](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/assistant/assistantService.ts): `backend/src/assistant/assistantService.ts`
- [Assistant tools](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/assistant/tools.ts): `backend/src/assistant/tools.ts`
- [Receipt scanning](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/mcp/geminiOcr.ts): `backend/src/mcp/geminiOcr.ts`
- [MCP server](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/mcp/server.ts): `backend/src/mcp/server.ts`
- [Personal access tokens](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/mcp/tokenStore.ts): `backend/src/mcp/tokenStore.ts`
- [Semantic search embeddings](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/mcp/embeddingsHelper.ts): `backend/src/mcp/embeddingsHelper.ts`

### Persistence

- [PostgreSQL store](https://github.com/nihar8262/expense-tracker/blob/master/backend/src/store/postgres.ts): `backend/src/store/postgres.ts`
- **PostgreSQL**

### Other components

- **Finance user**
- **Gemini embeddings API**

## Connections

- Finance user → React application: uses
- React application → Sign-in and session: authenticates (evidence: `frontend/src/App.tsx`)
- React application → Finance workspaces: renders
- Finance workspaces → API client: requests data (evidence: `frontend/src/services/api.ts`)
- API client → Express application: calls API
- Express application → Server authentication: authenticates requests (evidence: `backend/src/app.ts`)
- Express application → Request handlers: dispatches (evidence: `backend/src/app.ts`)
- Request handlers → Personal expenses: handles
- Request handlers → Budgets: handles (evidence: `backend/src/app.ts`)
- Request handlers → Shared wallets: handles (evidence: `backend/src/app.ts`)
- Request handlers → Peer loans: handles (evidence: `backend/src/app.ts`)
- Request handlers → Notifications and bills: handles (evidence: `backend/src/app.ts`)
- Request handlers → PostgreSQL store: reads and writes
- PostgreSQL store → PostgreSQL: persists data
- Express application → Finance assistant: routes requests (evidence: `backend/src/app.ts`)
- Finance assistant → Assistant tools: executes tools (evidence: `backend/src/assistant/assistantService.ts`)
- MCP server → Assistant tools: dispatches tools (evidence: `backend/src/mcp/server.ts`)
- MCP server → Personal access tokens: authenticates tokens (evidence: `backend/src/mcp/server.ts`)
- PostgreSQL store → Semantic search embeddings: saves embeddings (evidence: `backend/src/store/postgres.ts`)
- Semantic search embeddings → Gemini embeddings API: requests vectors
- Finance workspaces → Receipt scanning: scans receipts
- Finance user → MCP server: connects external tools
