# achyutha2546/nexspend architecture

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

- Interactive diagram: https://gitdiagram.com/achyutha2546/nexspend
- Repository: https://github.com/achyutha2546/nexspend

## Overview

NexSpend is a personal-finance application for tracking transactions and managing budgets, goals, recurring activity, reports, and related productivity features. The principal evidenced flow is an authenticated user entering through the dashboard, with transaction routes dispatching to transaction handlers that read and write transaction records. AI routes expose coaching, forecasting, scenario, and review capabilities; category detection also supports learned merchant mappings and receipt scanning. The tree and excerpts establish some route ownership and internal calls, but not most frontend-to-service or database wiring, so those links are omitted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/achyutha2546/nexspend/blob/main/frontend/src/App.tsx) (App routing), [`frontend/src/offline/syncEngine.ts`](https://github.com/achyutha2546/nexspend/blob/main/frontend/src/offline/syncEngine.ts) (Offline sync), [`backend/src/routes/aiRoutes.ts`](https://github.com/achyutha2546/nexspend/blob/main/backend/src/routes/aiRoutes.ts) (AI routes), [`backend/src/controllers/transactionController.ts`](https://github.com/achyutha2546/nexspend/blob/main/backend/src/controllers/transactionController.ts) (Transaction handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["App routing<br/>[App.tsx]"]
  node_dashboard["Finance pages"]
  node_txpage["Transactions page"]
  node_txservice["Transaction service"]
  node_apiclient["API client<br/>[api.ts]"]
  node_sync["Offline sync<br/>[syncEngine.ts]"]
  node_ai_page["AI coach<br/>[AICoachPage.tsx]"]
  node_aiservice["AI client service<br/>[aiService.ts]"]
end

subgraph group_finance["Finance workflows"]
  node_txroutes["Transaction routes"]
  node_authmw["Auth middleware<br/>[authMiddleware.ts]"]
  node_txcontroller["Transaction handlers"]
  node_otherfinance["Budget, goals, recurring"]
  node_analytics["Analytics and reports"]
end

subgraph group_ai["AI capabilities"]
  node_airoutes["AI routes<br/>[aiRoutes.ts]"]
  node_aicontroller["AI handlers<br/>[aiController.ts]"]
  node_aisvc["AI service<br/>[AIService.ts]"]
  node_engines["Financial engines"]
  node_category["Category detection"]
  node_provider["AI provider factory"]
end

subgraph group_state["Persistence and offline"]
  node_idb[("IndexedDB queue<br/>[idbStorage.ts]")]
  node_txmodel[("Transaction records<br/>[Transaction.ts]")]
  node_mapping[("Merchant mappings")]
end

node_user(("User"))
node_llm{{"LLM provider"}}

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_txpage
node_app -->|"routes to"| node_ai_page
node_txroutes -->|"guards routes"| node_authmw
node_txroutes -->|"dispatches"| node_txcontroller
node_txcontroller -->|"reads/writes"| node_txmodel
node_sync -->|"reads queue"| node_idb
node_sync -->|"removes synced items"| node_idb
node_sync -->|"sends queued actions"| node_apiclient
node_airoutes -->|"guards routes"| node_authmw
node_airoutes -->|"dispatches"| node_aicontroller
node_airoutes -->|"dispatches detection"| node_category
node_category -->|"reads/writes"| node_mapping
node_category -->|"requests classification"| node_provider
node_provider -.->|"selects provider"| node_llm
node_txcontroller -->|"invalidates cache"| node_aisvc

click node_app "https://github.com/achyutha2546/nexspend/blob/main/frontend/src/App.tsx"
click node_dashboard "https://github.com/achyutha2546/nexspend/tree/main/frontend/src/pages/dashboard"
click node_txpage "https://github.com/achyutha2546/nexspend/blob/main/frontend/src/pages/dashboard/TransactionsPage.tsx"
click node_txservice "https://github.com/achyutha2546/nexspend/blob/main/frontend/src/services/transactionService.ts"
click node_apiclient "https://github.com/achyutha2546/nexspend/blob/main/frontend/src/services/api.ts"
click node_sync "https://github.com/achyutha2546/nexspend/blob/main/frontend/src/offline/syncEngine.ts"
click node_idb "https://github.com/achyutha2546/nexspend/blob/main/frontend/src/offline/idbStorage.ts"
click node_txroutes "https://github.com/achyutha2546/nexspend/blob/main/backend/src/routes/transactionRoutes.ts"
click node_authmw "https://github.com/achyutha2546/nexspend/blob/main/backend/src/middleware/authMiddleware.ts"
click node_txcontroller "https://github.com/achyutha2546/nexspend/blob/main/backend/src/controllers/transactionController.ts"
click node_txmodel "https://github.com/achyutha2546/nexspend/blob/main/backend/src/models/Transaction.ts"
click node_otherfinance "https://github.com/achyutha2546/nexspend/tree/main/backend/src/controllers"
click node_analytics "https://github.com/achyutha2546/nexspend/blob/main/backend/src/controllers/analyticsController.ts"
click node_ai_page "https://github.com/achyutha2546/nexspend/blob/main/frontend/src/pages/dashboard/AICoachPage.tsx"
click node_aiservice "https://github.com/achyutha2546/nexspend/blob/main/frontend/src/services/aiService.ts"
click node_airoutes "https://github.com/achyutha2546/nexspend/blob/main/backend/src/routes/aiRoutes.ts"
click node_aicontroller "https://github.com/achyutha2546/nexspend/blob/main/backend/src/controllers/aiController.ts"
click node_aisvc "https://github.com/achyutha2546/nexspend/blob/main/backend/src/ai/services/AIService.ts"
click node_engines "https://github.com/achyutha2546/nexspend/tree/main/backend/src/ai/engines"
click node_category "https://github.com/achyutha2546/nexspend/blob/main/backend/src/controllers/categoryDetectionController.ts"
click node_mapping "https://github.com/achyutha2546/nexspend/blob/main/backend/src/models/MerchantCategoryMapping.ts"
click node_provider "https://github.com/achyutha2546/nexspend/blob/main/backend/src/ai/providers/AIProviderFactory.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_app,node_dashboard,node_txpage,node_txservice,node_apiclient,node_sync,node_ai_page,node_aiservice,node_user toneBlue
class node_txroutes,node_authmw,node_txcontroller,node_otherfinance,node_analytics toneAmber
class node_airoutes,node_aicontroller,node_aisvc,node_engines,node_category,node_provider toneMint
class node_idb,node_txmodel,node_mapping toneRose
class node_llm toneIndigo
```

## Components

### Web application

- [App routing](https://github.com/achyutha2546/nexspend/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Finance pages](https://github.com/achyutha2546/nexspend/tree/main/frontend/src/pages/dashboard): `frontend/src/pages/dashboard`
- [Transactions page](https://github.com/achyutha2546/nexspend/blob/main/frontend/src/pages/dashboard/TransactionsPage.tsx): `frontend/src/pages/dashboard/TransactionsPage.tsx`
- [Transaction service](https://github.com/achyutha2546/nexspend/blob/main/frontend/src/services/transactionService.ts): `frontend/src/services/transactionService.ts`
- [API client](https://github.com/achyutha2546/nexspend/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Offline sync](https://github.com/achyutha2546/nexspend/blob/main/frontend/src/offline/syncEngine.ts): `frontend/src/offline/syncEngine.ts`
- [AI coach](https://github.com/achyutha2546/nexspend/blob/main/frontend/src/pages/dashboard/AICoachPage.tsx): `frontend/src/pages/dashboard/AICoachPage.tsx`
- [AI client service](https://github.com/achyutha2546/nexspend/blob/main/frontend/src/services/aiService.ts): `frontend/src/services/aiService.ts`

### Finance workflows

- [Transaction routes](https://github.com/achyutha2546/nexspend/blob/main/backend/src/routes/transactionRoutes.ts): `backend/src/routes/transactionRoutes.ts`
- [Auth middleware](https://github.com/achyutha2546/nexspend/blob/main/backend/src/middleware/authMiddleware.ts): `backend/src/middleware/authMiddleware.ts`
- [Transaction handlers](https://github.com/achyutha2546/nexspend/blob/main/backend/src/controllers/transactionController.ts): `backend/src/controllers/transactionController.ts`
- [Budget, goals, recurring](https://github.com/achyutha2546/nexspend/tree/main/backend/src/controllers): `backend/src/controllers`
- [Analytics and reports](https://github.com/achyutha2546/nexspend/blob/main/backend/src/controllers/analyticsController.ts): `backend/src/controllers/analyticsController.ts`

### AI capabilities

- [AI routes](https://github.com/achyutha2546/nexspend/blob/main/backend/src/routes/aiRoutes.ts): `backend/src/routes/aiRoutes.ts`
- [AI handlers](https://github.com/achyutha2546/nexspend/blob/main/backend/src/controllers/aiController.ts): `backend/src/controllers/aiController.ts`
- [AI service](https://github.com/achyutha2546/nexspend/blob/main/backend/src/ai/services/AIService.ts): `backend/src/ai/services/AIService.ts`
- [Financial engines](https://github.com/achyutha2546/nexspend/tree/main/backend/src/ai/engines): `backend/src/ai/engines`
- [Category detection](https://github.com/achyutha2546/nexspend/blob/main/backend/src/controllers/categoryDetectionController.ts): `backend/src/controllers/categoryDetectionController.ts`
- [AI provider factory](https://github.com/achyutha2546/nexspend/blob/main/backend/src/ai/providers/AIProviderFactory.ts): `backend/src/ai/providers/AIProviderFactory.ts`

### Persistence and offline

- [IndexedDB queue](https://github.com/achyutha2546/nexspend/blob/main/frontend/src/offline/idbStorage.ts): `frontend/src/offline/idbStorage.ts`
- [Transaction records](https://github.com/achyutha2546/nexspend/blob/main/backend/src/models/Transaction.ts): `backend/src/models/Transaction.ts`
- [Merchant mappings](https://github.com/achyutha2546/nexspend/blob/main/backend/src/models/MerchantCategoryMapping.ts): `backend/src/models/MerchantCategoryMapping.ts`

### Other components

- **User**
- **LLM provider**

## Connections

- User → App routing: uses
- App routing → Finance pages: routes to
- App routing → Transactions page: routes to
- App routing → AI coach: routes to
- Transaction routes → Auth middleware: guards routes
- Transaction routes → Transaction handlers: dispatches
- Transaction handlers → Transaction records: reads/writes
- Offline sync → IndexedDB queue: reads queue
- Offline sync → IndexedDB queue: removes synced items
- Offline sync → API client: sends queued actions
- AI routes → Auth middleware: guards routes
- AI routes → AI handlers: dispatches
- AI routes → Category detection: dispatches detection
- Category detection → Merchant mappings: reads/writes
- Category detection → AI provider factory: requests classification
- AI provider factory → LLM provider: selects provider
- Transaction handlers → AI service: invalidates cache