# alakhnamdev/expensetracker architecture

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

- Interactive diagram: https://gitdiagram.com/alakhnamdev/expensetracker
- Repository: https://github.com/alakhnamdev/expensetracker

## Overview

This is a personal expense-tracking product: users authenticate, record expenses, manage category budgets, inspect financial summaries, and request personalized spending advice. The Next.js interface calls the Express service for primary account and finance operations; documented suggestions flow fetches expense data through Express, then submits it to the FastAPI analyzer. The graph separates user-facing features, core API/data, and analysis. Backend controller-to-model details and some feature wiring are inferred only where README/API documentation supports them; unsampled implementation links are omitted.

Main entry points: [`backend/src/server.js`](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/server.js) (Express server), [`backend/src/api/v1/routes.js`](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/api/v1/routes.js) (API v1 router), [`frontend/src/components/CreateExpenseForm/index.tsx`](https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/components/CreateExpenseForm/index.tsx) (Expense forms), [`frontend/src/utils/Suggestions/index.tsx`](https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/utils/Suggestions/index.tsx) (Suggestions page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User experience"]
  node_finance_ui["Finance pages<br/>[page.tsx]"]
  node_auth_ui["Account pages<br/>[page.tsx]"]
  node_expense_forms["Expense forms<br/>[index.tsx]"]
  node_budget_ui["Budget pages<br/>[page.tsx]"]
  node_dashboard_ui["Dashboard<br/>[index.tsx]"]
  node_suggestions_ui["Suggestions page<br/>[index.tsx]"]
  node_expense_client["Expense requests<br/>[CreateExpense.ts]"]
  node_budget_client["Budget requests<br/>[GetBudgets.ts]"]
  node_dashboard_client["Dashboard requests<br/>[index.tsx]"]
  node_reports_client["Report requests<br/>[index.ts]"]
end

subgraph group_core["Core finance API"]
  node_express_app["Express server<br/>[server.js]"]
  node_api_router["API v1 router<br/>[routes.js]"]
  node_auth_routes["Auth routes<br/>[auth.js]"]
  node_expense_routes["Expense routes<br/>[expenses.js]"]
  node_budget_routes["Budget routes<br/>[budgets.js]"]
  node_dashboard_routes["Dashboard routes<br/>[dashboard.js]"]
  node_report_routes["Report routes<br/>[reports.js]"]
  node_auth_controllers["Auth controllers<br/>[signup.js]"]
  node_expense_controller["Expense controller<br/>[expenses.js]"]
  node_budget_controller["Budget controller<br/>[budgets.js]"]
  node_dashboard_controller["Dashboard controller<br/>[dashboard.js]"]
  node_report_controller["Report controller<br/>[reports.js]"]
  node_report_job["Scheduled reports<br/>[reportGenerator.js]"]
  node_auth_middleware["JWT middleware<br/>[auth.js]"]
end

subgraph group_storage["Persistence"]
  node_expense_model["Expense model<br/>[expense.js]"]
  node_budget_model["Budget model<br/>[budget.js]"]
  node_user_model["User model<br/>[user.js]"]
  node_database[("Database connection<br/>[db.js]")]
end

subgraph group_analysis["Suggestions analysis"]
  node_analysis_app["Analysis API<br/>[main.py]"]
  node_analysis_routes["Suggestions route<br/>[suggestions.py]"]
  node_analyzer["Financial analyzer<br/>[analyzer.py]"]
end

node_user(("Finance user"))

node_user -->|"uses"| node_auth_ui
node_user -->|"manages finances"| node_finance_ui
node_user -->|"sets budgets"| node_budget_ui
node_user -->|"reviews spending"| node_dashboard_ui
node_user -->|"requests advice"| node_suggestions_ui
node_finance_ui -->|"creates expenses"| node_expense_forms
node_expense_forms -->|"loads categories"| node_budget_client
node_expense_forms -->|"submits expense"| node_expense_client
node_auth_ui -->|"authenticates"| node_express_app
node_expense_client -->|"sends expense requests"| node_express_app
node_budget_client -->|"requests budgets"| node_express_app
node_dashboard_ui -->|"loads metrics"| node_dashboard_client
node_dashboard_client -->|"requests summaries"| node_express_app
node_reports_client -->|"requests reports"| node_express_app
node_suggestions_ui -->|"fetches expenses"| node_expense_client
node_suggestions_ui -->|"submits expense data"| node_analysis_app
node_express_app -->|"mounts API"| node_api_router
node_api_router -->|"dispatches auth"| node_auth_routes
node_api_router -->|"dispatches expenses"| node_expense_routes
node_api_router -->|"dispatches budgets"| node_budget_routes
node_api_router -->|"dispatches metrics"| node_dashboard_routes
node_api_router -->|"dispatches reports"| node_report_routes
node_auth_routes -->|"dispatches"| node_auth_controllers
node_expense_routes -->|"dispatches"| node_expense_controller
node_budget_routes -->|"dispatches"| node_budget_controller
node_dashboard_routes -->|"dispatches"| node_dashboard_controller
node_report_routes -->|"dispatches"| node_report_controller
node_auth_routes -->|"protects details"| node_auth_middleware
node_auth_controllers -->|"uses account data"| node_user_model
node_expense_controller -->|"manages expenses"| node_expense_model
node_budget_controller -->|"manages budgets"| node_budget_model
node_dashboard_controller -->|"aggregates spending"| node_expense_model
node_report_controller -->|"reads spending"| node_expense_model
node_report_job -->|"generates reports"| node_report_controller
node_express_app -->|"connects"| node_database
node_analysis_app -->|"mounts routes"| node_analysis_routes
node_analysis_routes -->|"analyzes expenses"| node_analyzer

click node_finance_ui "https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/app/expenses/page.tsx"
click node_auth_ui "https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/app/login/page.tsx"
click node_expense_forms "https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/components/CreateExpenseForm/index.tsx"
click node_budget_ui "https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/app/budgets/page.tsx"
click node_dashboard_ui "https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/components/Dashboard/index.tsx"
click node_suggestions_ui "https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/utils/Suggestions/index.tsx"
click node_expense_client "https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/utils/Expense/CreateExpense.ts"
click node_budget_client "https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/utils/Budget/GetBudgets.ts"
click node_dashboard_client "https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/utils/Dashboard/index.tsx"
click node_reports_client "https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/utils/Reports/index.ts"
click node_express_app "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/server.js"
click node_api_router "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/api/v1/routes.js"
click node_auth_routes "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/api/v1/endpoints/auth.js"
click node_expense_routes "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/api/v1/endpoints/expenses.js"
click node_budget_routes "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/api/v1/endpoints/budgets.js"
click node_dashboard_routes "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/api/v1/endpoints/dashboard.js"
click node_report_routes "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/api/v1/endpoints/reports.js"
click node_auth_controllers "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/controllers/signup.js"
click node_expense_controller "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/controllers/expenses.js"
click node_budget_controller "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/controllers/budgets.js"
click node_dashboard_controller "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/controllers/dashboard.js"
click node_report_controller "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/controllers/reports.js"
click node_report_job "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/cronjob/reportGenerator.js"
click node_auth_middleware "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/middleware/auth.js"
click node_expense_model "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/models/expense.js"
click node_budget_model "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/models/budget.js"
click node_user_model "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/models/user.js"
click node_database "https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/config/db.js"
click node_analysis_app "https://github.com/alakhnamdev/expensetracker/blob/main/FastAPI/main.py"
click node_analysis_routes "https://github.com/alakhnamdev/expensetracker/blob/main/FastAPI/api/v1/endpoints/suggestions.py"
click node_analyzer "https://github.com/alakhnamdev/expensetracker/blob/main/FastAPI/controllers/analyzer.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_finance_ui,node_auth_ui,node_expense_forms,node_budget_ui,node_dashboard_ui,node_suggestions_ui,node_expense_client,node_budget_client,node_dashboard_client,node_reports_client,node_user toneBlue
class node_express_app,node_api_router,node_auth_routes,node_expense_routes,node_budget_routes,node_dashboard_routes,node_report_routes,node_auth_controllers,node_expense_controller,node_budget_controller,node_dashboard_controller,node_report_controller,node_report_job,node_auth_middleware toneAmber
class node_expense_model,node_budget_model,node_user_model,node_database toneMint
class node_analysis_app,node_analysis_routes,node_analyzer toneRose
```

## Components

### User experience

- [Finance pages](https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/app/expenses/page.tsx): `frontend/src/app/expenses/page.tsx`
- [Account pages](https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/app/login/page.tsx): `frontend/src/app/login/page.tsx`
- [Expense forms](https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/components/CreateExpenseForm/index.tsx): `frontend/src/components/CreateExpenseForm/index.tsx`
- [Budget pages](https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/app/budgets/page.tsx): `frontend/src/app/budgets/page.tsx`
- [Dashboard](https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/components/Dashboard/index.tsx): `frontend/src/components/Dashboard/index.tsx`
- [Suggestions page](https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/utils/Suggestions/index.tsx): `frontend/src/utils/Suggestions/index.tsx`
- [Expense requests](https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/utils/Expense/CreateExpense.ts): `frontend/src/utils/Expense/CreateExpense.ts`
- [Budget requests](https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/utils/Budget/GetBudgets.ts): `frontend/src/utils/Budget/GetBudgets.ts`
- [Dashboard requests](https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/utils/Dashboard/index.tsx): `frontend/src/utils/Dashboard/index.tsx`
- [Report requests](https://github.com/alakhnamdev/expensetracker/blob/main/frontend/src/utils/Reports/index.ts): `frontend/src/utils/Reports/index.ts`

### Core finance API

- [Express server](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/server.js): `backend/src/server.js`
- [API v1 router](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/api/v1/routes.js): `backend/src/api/v1/routes.js`
- [Auth routes](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/api/v1/endpoints/auth.js): `backend/src/api/v1/endpoints/auth.js`
- [Expense routes](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/api/v1/endpoints/expenses.js): `backend/src/api/v1/endpoints/expenses.js`
- [Budget routes](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/api/v1/endpoints/budgets.js): `backend/src/api/v1/endpoints/budgets.js`
- [Dashboard routes](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/api/v1/endpoints/dashboard.js): `backend/src/api/v1/endpoints/dashboard.js`
- [Report routes](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/api/v1/endpoints/reports.js): `backend/src/api/v1/endpoints/reports.js`
- [Auth controllers](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/controllers/signup.js): `backend/src/controllers/signup.js`
- [Expense controller](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/controllers/expenses.js): `backend/src/controllers/expenses.js`
- [Budget controller](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/controllers/budgets.js): `backend/src/controllers/budgets.js`
- [Dashboard controller](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/controllers/dashboard.js): `backend/src/controllers/dashboard.js`
- [Report controller](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/controllers/reports.js): `backend/src/controllers/reports.js`
- [Scheduled reports](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/cronjob/reportGenerator.js): `backend/src/cronjob/reportGenerator.js`
- [JWT middleware](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/middleware/auth.js): `backend/src/middleware/auth.js`

### Persistence

- [Expense model](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/models/expense.js): `backend/src/models/expense.js`
- [Budget model](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/models/budget.js): `backend/src/models/budget.js`
- [User model](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/models/user.js): `backend/src/models/user.js`
- [Database connection](https://github.com/alakhnamdev/expensetracker/blob/main/backend/src/config/db.js): `backend/src/config/db.js`

### Suggestions analysis

- [Analysis API](https://github.com/alakhnamdev/expensetracker/blob/main/FastAPI/main.py): `FastAPI/main.py`
- [Suggestions route](https://github.com/alakhnamdev/expensetracker/blob/main/FastAPI/api/v1/endpoints/suggestions.py): `FastAPI/api/v1/endpoints/suggestions.py`
- [Financial analyzer](https://github.com/alakhnamdev/expensetracker/blob/main/FastAPI/controllers/analyzer.py): `FastAPI/controllers/analyzer.py`

### Other components

- **Finance user**

## Connections

- Finance user → Account pages: uses
- Finance user → Finance pages: manages finances
- Finance user → Budget pages: sets budgets
- Finance user → Dashboard: reviews spending
- Finance user → Suggestions page: requests advice
- Finance pages → Expense forms: creates expenses
- Expense forms → Budget requests: loads categories
- Expense forms → Expense requests: submits expense
- Account pages → Express server: authenticates
- Expense requests → Express server: sends expense requests
- Budget requests → Express server: requests budgets
- Dashboard → Dashboard requests: loads metrics
- Dashboard requests → Express server: requests summaries
- Report requests → Express server: requests reports
- Suggestions page → Expense requests: fetches expenses
- Suggestions page → Analysis API: submits expense data
- Express server → API v1 router: mounts API
- API v1 router → Auth routes: dispatches auth
- API v1 router → Expense routes: dispatches expenses
- API v1 router → Budget routes: dispatches budgets
- API v1 router → Dashboard routes: dispatches metrics
- API v1 router → Report routes: dispatches reports
- Auth routes → Auth controllers: dispatches
- Expense routes → Expense controller: dispatches
- Budget routes → Budget controller: dispatches
- Dashboard routes → Dashboard controller: dispatches
- Report routes → Report controller: dispatches
- Auth routes → JWT middleware: protects details
- Auth controllers → User model: uses account data
- Expense controller → Expense model: manages expenses
- Budget controller → Budget model: manages budgets
- Dashboard controller → Expense model: aggregates spending
- Report controller → Expense model: reads spending
- Scheduled reports → Report controller: generates reports
- Express server → Database connection: connects
- Analysis API → Suggestions route: mounts routes
- Suggestions route → Financial analyzer: analyzes expenses