# nareshjo001/expense-manager architecture

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

- Interactive diagram: https://gitdiagram.com/nareshjo001/expense-manager
- Repository: https://github.com/nareshjo001/expense-manager

## Overview

BALENISA is a full-stack personal-finance platform: users record and import financial activity, manage budgets and recurring expenses, then explore charts, insights, and grounded SIA answers. The React client calls an Express API, which owns authorization, financial writes, analytics, and external-service calls. Major documented branches include receipt OCR, exports, notifications, and category prediction/retraining. Some subsystem links are documented only at a high level; unsampled implementation details are not inferred.

Main entry points: [`backend/app.js`](https://github.com/nareshjo001/expense-manager/blob/main/backend/app.js) (Express API), [`backend/config/Schemas.js`](https://github.com/nareshjo001/expense-manager/blob/main/backend/config/Schemas.js) (MongoDB), [`backend/Routes/api.routes.js`](https://github.com/nareshjo001/expense-manager/blob/main/backend/Routes/api.routes.js) (API routes), [`backend/sia/semanticPipeline.js`](https://github.com/nareshjo001/expense-manager/blob/main/backend/sia/semanticPipeline.js) (Grounded query pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_frontend["Finance UI<br/>[App.js]"]
  node_client_api["API clients<br/>[axios.js]"]
end

subgraph group_finance["Finance API"]
  node_auth["Authentication<br/>[login.js]"]
  node_api["Express API<br/>[app.js]"]
  node_routes["API routes<br/>[api.routes.js]"]
  node_transactions["Expenses and income<br/>[addexpense.js]"]
  node_budgets["Budgets<br/>[setbudget.js]"]
  node_recurring["Recurring expenses<br/>[recurring.js]"]
  node_imports["Import sessions<br/>[createSession.js]"]
  node_exports["Data exports<br/>[create.js]"]
  node_receipts["Receipt OCR and inbox"]
end

subgraph group_insights["Analytics and SIA"]
  node_charts["Charts<br/>[chart.service.js]"]
  node_reports["Financial insights<br/>[reportGenerator.js]"]
  node_sia["SIA assistant<br/>[ask.js]"]
  node_sia_pipeline["Grounded query pipeline"]
end

subgraph group_operations["Platform services"]
  node_finance_db[("MongoDB<br/>[Schemas.js]")]
  node_redis[("Redis cache<br/>[redis.js]")]
  node_ml_client["ML service client<br/>[mlServiceClient.js]"]
end

subgraph group_ml["ML service"]
  node_ml_api["Category prediction<br/>[app.py]"]
  node_model["Live model manager"]
  node_retraining["Model retraining"]
end

node_user(("User"))
node_llm["LLM provider"]
node_push["Firebase push"]

node_user -->|"uses"| node_frontend
node_frontend -->|"requests"| node_client_api
node_client_api -->|"REST calls"| node_api
node_api -->|"mounts routes"| node_auth
node_api -->|"mounts"| node_routes
node_routes -->|"routes to"| node_budgets
node_routes -->|"routes to"| node_recurring
node_routes -->|"routes to"| node_imports
node_routes -->|"routes to"| node_exports
node_api -->|"serves routes"| node_transactions
node_api -->|"serves routes"| node_receipts
node_api -->|"serves routes"| node_charts
node_api -->|"serves routes"| node_reports
node_api -->|"serves routes"| node_sia
node_transactions -->|"writes data"| node_finance_db
node_budgets -->|"stores budgets"| node_finance_db
node_recurring -->|"stores definitions"| node_finance_db
node_imports -->|"stores sessions"| node_finance_db
node_exports -.->|"reads finance data"| node_finance_db
node_receipts -->|"persists receipts"| node_finance_db
node_charts -->|"reads activity"| node_finance_db
node_reports -->|"reads activity"| node_finance_db
node_sia -->|"uses pipeline"| node_sia_pipeline
node_sia_pipeline -->|"queries user facts"| node_finance_db
node_sia_pipeline -.->|"optional explanation"| node_llm
node_api -->|"uses cache"| node_redis
node_api -->|"requests predictions"| node_ml_client
node_ml_client -->|"service calls"| node_ml_api
node_ml_api -->|"loads predictor"| node_model
node_ml_api -->|"starts retraining"| node_retraining
node_api -->|"sends notifications"| node_push

click node_frontend "https://github.com/nareshjo001/expense-manager/blob/main/frontend/src/App.js"
click node_client_api "https://github.com/nareshjo001/expense-manager/blob/main/frontend/src/api/axios.js"
click node_auth "https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/AuthControllers/login.js"
click node_api "https://github.com/nareshjo001/expense-manager/blob/main/backend/app.js"
click node_routes "https://github.com/nareshjo001/expense-manager/blob/main/backend/Routes/api.routes.js"
click node_transactions "https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/ExpenseControllers/addexpense.js"
click node_budgets "https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/BudgetControllers/setbudget.js"
click node_recurring "https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/RecurringExpenses/recurring.js"
click node_imports "https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/ImportControllers/createSession.js"
click node_exports "https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/Export/create.js"
click node_receipts "https://github.com/nareshjo001/expense-manager/blob/main/backend/Services/ReceiptServices/receiptIngestService.js"
click node_finance_db "https://github.com/nareshjo001/expense-manager/blob/main/backend/config/Schemas.js"
click node_redis "https://github.com/nareshjo001/expense-manager/blob/main/backend/config/redis.js"
click node_charts "https://github.com/nareshjo001/expense-manager/blob/main/backend/Services/ChartServices/chart.service.js"
click node_reports "https://github.com/nareshjo001/expense-manager/blob/main/backend/analytics/reportGenerator.js"
click node_sia "https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/SiaControllers/ask.js"
click node_sia_pipeline "https://github.com/nareshjo001/expense-manager/blob/main/backend/sia/semanticPipeline.js"
click node_ml_client "https://github.com/nareshjo001/expense-manager/blob/main/backend/utils/mlServiceClient.js"
click node_ml_api "https://github.com/nareshjo001/expense-manager/blob/main/ml-service/app.py"
click node_model "https://github.com/nareshjo001/expense-manager/blob/main/ml-service/inference/predictor_manager.py"
click node_retraining "https://github.com/nareshjo001/expense-manager/blob/main/ml-service/training/retrain_pipeline.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_frontend,node_client_api,node_user toneBlue
class node_auth,node_api,node_routes,node_transactions,node_budgets,node_recurring,node_imports,node_exports,node_receipts toneAmber
class node_charts,node_reports,node_sia,node_sia_pipeline toneMint
class node_finance_db,node_redis,node_ml_client toneRose
class node_ml_api,node_model,node_retraining,node_llm,node_push toneIndigo
```

## Components

### React client

- [Finance UI](https://github.com/nareshjo001/expense-manager/blob/main/frontend/src/App.js): `frontend/src/App.js`
- [API clients](https://github.com/nareshjo001/expense-manager/blob/main/frontend/src/api/axios.js): `frontend/src/api/axios.js`

### Finance API

- [Authentication](https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/AuthControllers/login.js): `backend/Controllers/AuthControllers/login.js`
- [Express API](https://github.com/nareshjo001/expense-manager/blob/main/backend/app.js): `backend/app.js`
- [API routes](https://github.com/nareshjo001/expense-manager/blob/main/backend/Routes/api.routes.js): `backend/Routes/api.routes.js`
- [Expenses and income](https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/ExpenseControllers/addexpense.js): `backend/Controllers/ExpenseControllers/addexpense.js`
- [Budgets](https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/BudgetControllers/setbudget.js): `backend/Controllers/BudgetControllers/setbudget.js`
- [Recurring expenses](https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/RecurringExpenses/recurring.js): `backend/Controllers/RecurringExpenses/recurring.js`
- [Import sessions](https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/ImportControllers/createSession.js): `backend/Controllers/ImportControllers/createSession.js`
- [Data exports](https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/Export/create.js): `backend/Controllers/Export/create.js`
- [Receipt OCR and inbox](https://github.com/nareshjo001/expense-manager/blob/main/backend/Services/ReceiptServices/receiptIngestService.js): `backend/Services/ReceiptServices/receiptIngestService.js`

### Analytics and SIA

- [Charts](https://github.com/nareshjo001/expense-manager/blob/main/backend/Services/ChartServices/chart.service.js): `backend/Services/ChartServices/chart.service.js`
- [Financial insights](https://github.com/nareshjo001/expense-manager/blob/main/backend/analytics/reportGenerator.js): `backend/analytics/reportGenerator.js`
- [SIA assistant](https://github.com/nareshjo001/expense-manager/blob/main/backend/Controllers/SiaControllers/ask.js): `backend/Controllers/SiaControllers/ask.js`
- [Grounded query pipeline](https://github.com/nareshjo001/expense-manager/blob/main/backend/sia/semanticPipeline.js): `backend/sia/semanticPipeline.js`

### Platform services

- [MongoDB](https://github.com/nareshjo001/expense-manager/blob/main/backend/config/Schemas.js): `backend/config/Schemas.js`
- [Redis cache](https://github.com/nareshjo001/expense-manager/blob/main/backend/config/redis.js): `backend/config/redis.js`
- [ML service client](https://github.com/nareshjo001/expense-manager/blob/main/backend/utils/mlServiceClient.js): `backend/utils/mlServiceClient.js`

### ML service

- [Category prediction](https://github.com/nareshjo001/expense-manager/blob/main/ml-service/app.py): `ml-service/app.py`
- [Live model manager](https://github.com/nareshjo001/expense-manager/blob/main/ml-service/inference/predictor_manager.py): `ml-service/inference/predictor_manager.py`
- [Model retraining](https://github.com/nareshjo001/expense-manager/blob/main/ml-service/training/retrain_pipeline.py): `ml-service/training/retrain_pipeline.py`

### Other components

- **User**
- **LLM provider**
- **Firebase push**

## Connections

- User → Finance UI: uses (evidence: `README.md`)
- Finance UI → API clients: requests (evidence: `README.md`)
- API clients → Express API: REST calls (evidence: `README.md`)
- Express API → Authentication: mounts routes (evidence: `backend/app.js`)
- Express API → API routes: mounts (evidence: `backend/app.js`)
- API routes → Budgets: routes to (evidence: `backend/Routes/api.routes.js`)
- API routes → Recurring expenses: routes to (evidence: `backend/Routes/api.routes.js`)
- API routes → Import sessions: routes to (evidence: `backend/Routes/api.routes.js`)
- API routes → Data exports: routes to (evidence: `backend/Routes/api.routes.js`)
- Express API → Expenses and income: serves routes (evidence: `backend/app.js`)
- Express API → Receipt OCR and inbox: serves routes (evidence: `backend/app.js`)
- Express API → Charts: serves routes (evidence: `backend/app.js`)
- Express API → Financial insights: serves routes (evidence: `backend/app.js`)
- Express API → SIA assistant: serves routes (evidence: `backend/app.js`)
- Expenses and income → MongoDB: writes data (evidence: `README.md`)
- Budgets → MongoDB: stores budgets (evidence: `README.md`)
- Recurring expenses → MongoDB: stores definitions (evidence: `README.md`)
- Import sessions → MongoDB: stores sessions
- Data exports → MongoDB: reads finance data
- Receipt OCR and inbox → MongoDB: persists receipts (evidence: `backend/Services/ReceiptServices/receiptIngestService.js`)
- Charts → MongoDB: reads activity (evidence: `README.md`)
- Financial insights → MongoDB: reads activity (evidence: `README.md`)
- SIA assistant → Grounded query pipeline: uses pipeline (evidence: `backend/sia/semanticPipeline.js`)
- Grounded query pipeline → MongoDB: queries user facts
- Grounded query pipeline → LLM provider: optional explanation (evidence: `README.md`)
- Express API → Redis cache: uses cache (evidence: `README.md`)
- Express API → ML service client: requests predictions (evidence: `backend/utils/mlServiceClient.js`)
- ML service client → Category prediction: service calls (evidence: `README.md`)
- Category prediction → Live model manager: loads predictor (evidence: `ml-service/app.py`)
- Category prediction → Model retraining: starts retraining (evidence: `ml-service/app.py`)
- Express API → Firebase push: sends notifications (evidence: `README.md`)
