# srisaravanan55/smartbudget-ai architecture

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

- Interactive diagram: https://gitdiagram.com/srisaravanan55/smartbudget-ai
- Repository: https://github.com/srisaravanan55/smartbudget-ai

## Overview

SmartBudget AI is a full-stack personal-finance advisor: users authenticate, set a financial profile, log natural-language expenses, and review budgets, health scores, and reports. The React UI calls protected FastAPI routes; those routes delegate domain work to the orchestrator and specialized agents, with SQL-backed financial state and optional RAG/LLM assistance. Edges reflect explicit README statements or shown calls/import references; unsampled route and agent internals limit finer-grained links.

Main entry points: [`app/orchestrator.py`](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/orchestrator.py) (Orchestrator), [`main.py`](https://github.com/srisaravanan55/smartbudget-ai/blob/main/main.py) (FastAPI app), [`app/api/deps.py`](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/api/deps.py) (Auth dependency), [`app/api/v1/routes_profile.py`](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/api/v1/routes_profile.py) (Profile route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_react["React app<br/>[App.jsx]"]
  node_authctx["Auth state<br/>[AuthContext.jsx]"]
  node_http["API client<br/>[api.js]"]
  node_pages["Finance pages"]
end

subgraph group_api["API and identity"]
  node_gateway["FastAPI app<br/>[main.py]"]
  node_authroutes["Auth routes<br/>[routes_auth.py]"]
  node_authsvc["Auth service<br/>[auth_service.py]"]
  node_security["JWT security<br/>[security.py]"]
  node_authdeps["Auth dependency<br/>[deps.py]"]
  node_errors["Error handling<br/>[exceptions.py]"]
  node_schemas["API schemas<br/>[models.py]"]
end

subgraph group_finance["Finance workflows"]
  node_profile_route["Profile route<br/>[routes_profile.py]"]
  node_expense_route["Expense route<br/>[routes_expense.py]"]
  node_budget_route["Budget &amp; reports<br/>[routes_budget.py]"]
  node_orchestrator["Orchestrator<br/>[orchestrator.py]"]
end

subgraph group_intelligence["Advisor agents"]
  node_profiling["Profile agent<br/>[profiling_agent.py]"]
  node_categorization["Categorization"]
  node_budget_agent["Budget agent<br/>[budget_agent.py]"]
  node_debt_agent["Debt &amp; savings"]
  node_health_agent["Health scoring"]
  node_investment["Investment advice"]
  node_report_agent["Report agent<br/>[report_agent.py]"]
end

subgraph group_data["Persistence and AI"]
  node_sql[("Finance database<br/>[db.py]")]
  node_llm["LLM access<br/>[llm.py]"]
  node_rag[("Knowledge base<br/>[knowledge_base.py]")]
end

node_person(("User"))

node_person -->|"uses"| node_react
node_react -->|"provides auth"| node_authctx
node_react -->|"routes to"| node_pages
node_authctx -->|"calls"| node_http
node_pages -->|"requests data"| node_http
node_http -->|"sends API calls"| node_gateway
node_gateway -->|"registers routes"| node_authroutes
node_gateway -->|"registers routes"| node_profile_route
node_gateway -->|"registers routes"| node_expense_route
node_gateway -->|"registers routes"| node_budget_route
node_authroutes -->|"delegates"| node_authsvc
node_authsvc -->|"issues tokens"| node_security
node_authsvc -->|"reads and writes"| node_sql
node_authroutes -->|"uses schemas"| node_schemas
node_profile_route -->|"requires user"| node_authdeps
node_expense_route -->|"requires user"| node_authdeps
node_budget_route -->|"requires user"| node_authdeps
node_authdeps -->|"decodes token"| node_security
node_authdeps -->|"loads user"| node_sql
node_profile_route -->|"delegates"| node_orchestrator
node_expense_route -->|"delegates"| node_orchestrator
node_budget_route -->|"delegates"| node_orchestrator
node_orchestrator -->|"coordinates"| node_profiling
node_orchestrator -->|"categorizes"| node_categorization
node_orchestrator -->|"generates budgets"| node_budget_agent
node_orchestrator -->|"computes plans"| node_debt_agent
node_orchestrator -->|"scores finances"| node_health_agent
node_orchestrator -->|"compiles report"| node_report_agent
node_orchestrator -->|"reads and writes"| node_sql
node_categorization -->|"uses"| node_llm
node_report_agent -->|"uses"| node_llm
node_investment -.->|"gets tips"| node_rag
node_gateway -->|"registers handlers"| node_errors
node_profile_route -->|"uses schemas"| node_schemas
node_expense_route -->|"uses schemas"| node_schemas
node_budget_route -->|"uses schemas"| node_schemas

click node_react "https://github.com/srisaravanan55/smartbudget-ai/blob/main/frontend/src/App.jsx"
click node_authctx "https://github.com/srisaravanan55/smartbudget-ai/blob/main/frontend/src/context/AuthContext.jsx"
click node_http "https://github.com/srisaravanan55/smartbudget-ai/blob/main/frontend/src/api.js"
click node_pages "https://github.com/srisaravanan55/smartbudget-ai/tree/main/frontend/src/pages"
click node_gateway "https://github.com/srisaravanan55/smartbudget-ai/blob/main/main.py"
click node_authroutes "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/api/v1/routes_auth.py"
click node_authsvc "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/services/auth_service.py"
click node_security "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/core/security.py"
click node_authdeps "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/api/deps.py"
click node_profile_route "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/api/v1/routes_profile.py"
click node_expense_route "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/api/v1/routes_expense.py"
click node_budget_route "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/api/v1/routes_budget.py"
click node_orchestrator "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/orchestrator.py"
click node_profiling "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/profiling_agent.py"
click node_categorization "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/categorization_agent.py"
click node_budget_agent "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/budget_agent.py"
click node_debt_agent "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/debt_savings_agent.py"
click node_health_agent "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/health_score_agent.py"
click node_investment "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/investment_agent.py"
click node_report_agent "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/report_agent.py"
click node_sql "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/db.py"
click node_llm "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/llm.py"
click node_rag "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/rag/knowledge_base.py"
click node_errors "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/core/exceptions.py"
click node_schemas "https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/models.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_react,node_authctx,node_http,node_pages,node_person toneBlue
class node_gateway,node_authroutes,node_authsvc,node_security,node_authdeps,node_errors,node_schemas toneAmber
class node_profile_route,node_expense_route,node_budget_route,node_orchestrator toneMint
class node_profiling,node_categorization,node_budget_agent,node_debt_agent,node_health_agent,node_investment,node_report_agent toneRose
class node_sql,node_llm,node_rag toneIndigo
```

## Components

### Web client

- [React app](https://github.com/srisaravanan55/smartbudget-ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth state](https://github.com/srisaravanan55/smartbudget-ai/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [API client](https://github.com/srisaravanan55/smartbudget-ai/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Finance pages](https://github.com/srisaravanan55/smartbudget-ai/tree/main/frontend/src/pages): `frontend/src/pages`

### API and identity

- [FastAPI app](https://github.com/srisaravanan55/smartbudget-ai/blob/main/main.py): `main.py`
- [Auth routes](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/api/v1/routes_auth.py): `app/api/v1/routes_auth.py`
- [Auth service](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/services/auth_service.py): `app/services/auth_service.py`
- [JWT security](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/core/security.py): `app/core/security.py`
- [Auth dependency](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/api/deps.py): `app/api/deps.py`
- [Error handling](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/core/exceptions.py): `app/core/exceptions.py`
- [API schemas](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/models.py): `app/models.py`

### Finance workflows

- [Profile route](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/api/v1/routes_profile.py): `app/api/v1/routes_profile.py`
- [Expense route](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/api/v1/routes_expense.py): `app/api/v1/routes_expense.py`
- [Budget & reports](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/api/v1/routes_budget.py): `app/api/v1/routes_budget.py`
- [Orchestrator](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/orchestrator.py): `app/orchestrator.py`

### Advisor agents

- [Profile agent](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/profiling_agent.py): `app/agents/profiling_agent.py`
- [Categorization](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/categorization_agent.py): `app/agents/categorization_agent.py`
- [Budget agent](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/budget_agent.py): `app/agents/budget_agent.py`
- [Debt & savings](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/debt_savings_agent.py): `app/agents/debt_savings_agent.py`
- [Health scoring](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/health_score_agent.py): `app/agents/health_score_agent.py`
- [Investment advice](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/investment_agent.py): `app/agents/investment_agent.py`
- [Report agent](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/agents/report_agent.py): `app/agents/report_agent.py`

### Persistence and AI

- [Finance database](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/db.py): `app/db.py`
- [LLM access](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/llm.py): `app/llm.py`
- [Knowledge base](https://github.com/srisaravanan55/smartbudget-ai/blob/main/app/rag/knowledge_base.py): `app/rag/knowledge_base.py`

### Other components

- **User**

## Connections

- User → React app: uses
- React app → Auth state: provides auth (evidence: `frontend/src/App.jsx`)
- React app → Finance pages: routes to (evidence: `frontend/src/App.jsx`)
- Auth state → API client: calls (evidence: `frontend/src/context/AuthContext.jsx`)
- Finance pages → API client: requests data (evidence: `frontend/src/pages/Budget.jsx`)
- API client → FastAPI app: sends API calls
- FastAPI app → Auth routes: registers routes (evidence: `main.py`)
- FastAPI app → Profile route: registers routes (evidence: `main.py`)
- FastAPI app → Expense route: registers routes (evidence: `main.py`)
- FastAPI app → Budget & reports: registers routes (evidence: `main.py`)
- Auth routes → Auth service: delegates (evidence: `app/api/v1/routes_auth.py`)
- Auth service → JWT security: issues tokens (evidence: `app/services/auth_service.py`)
- Auth service → Finance database: reads and writes (evidence: `app/services/auth_service.py`)
- Auth routes → API schemas: uses schemas (evidence: `app/api/v1/routes_auth.py`)
- Profile route → Auth dependency: requires user (evidence: `app/api/v1/routes_profile.py`)
- Expense route → Auth dependency: requires user (evidence: `app/api/v1/routes_expense.py`)
- Budget & reports → Auth dependency: requires user (evidence: `app/api/v1/routes_budget.py`)
- Auth dependency → JWT security: decodes token (evidence: `app/api/deps.py`)
- Auth dependency → Finance database: loads user (evidence: `app/api/deps.py`)
- Profile route → Orchestrator: delegates (evidence: `app/api/v1/routes_profile.py`)
- Expense route → Orchestrator: delegates (evidence: `app/api/v1/routes_expense.py`)
- Budget & reports → Orchestrator: delegates (evidence: `app/api/v1/routes_budget.py`)
- Orchestrator → Profile agent: coordinates (evidence: `app/orchestrator.py`)
- Orchestrator → Categorization: categorizes (evidence: `app/orchestrator.py`)
- Orchestrator → Budget agent: generates budgets (evidence: `app/orchestrator.py`)
- Orchestrator → Debt & savings: computes plans (evidence: `app/orchestrator.py`)
- Orchestrator → Health scoring: scores finances (evidence: `app/orchestrator.py`)
- Orchestrator → Report agent: compiles report (evidence: `app/orchestrator.py`)
- Orchestrator → Finance database: reads and writes (evidence: `app/orchestrator.py`)
- Categorization → LLM access: uses (evidence: `app/agents/categorization_agent.py`)
- Report agent → LLM access: uses (evidence: `app/agents/report_agent.py`)
- Investment advice → Knowledge base: gets tips (evidence: `app/agents/investment_agent.py`)
- FastAPI app → Error handling: registers handlers (evidence: `main.py`)
- Profile route → API schemas: uses schemas (evidence: `app/api/v1/routes_profile.py`)
- Expense route → API schemas: uses schemas (evidence: `app/api/v1/routes_expense.py`)
- Budget & reports → API schemas: uses schemas (evidence: `app/api/v1/routes_budget.py`)
