# muuhesham/finance-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/muuhesham/finance-tracker
- Repository: https://github.com/muuhesham/finance-tracker

## Overview

FinanceFlow is a personal-finance web app for authentication, income and expense management, monthly summaries, visualizations, and rule-based insights. A user signs in, selects a month, views dashboard data and tips, and can add, edit, or delete transactions; dashboard changes trigger data reloads. The backend separates HTTP routing, controllers, services, and MongoDB models. The README documents Google OAuth and insight-generation capabilities; some service and route implementations were not excerpted, so uncertain internal links are omitted or marked unverified.

Main entry points: [`backend/src/app.js`](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/app.js) (Express app), [`frontend/src/features/dashboard/DashboardPage.jsx`](https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/features/dashboard/DashboardPage.jsx) (Monthly dashboard), [`frontend/src/api/client.js`](https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/api/client.js) (API client), [`frontend/src/app/App.jsx`](https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/app/App.jsx) (App routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["App routing<br/>[App.jsx]"]
  node_api_client["API client<br/>[client.js]"]
  node_dashboard_ui["Monthly dashboard<br/>[DashboardPage.jsx]"]
  node_charts["Dashboard charts"]
end

subgraph group_identity["Identity"]
  node_auth_ui["Sign-in UI<br/>[AuthPage.jsx]"]
  node_google_callback["OAuth callback UI"]
  node_session["Session context<br/>[AuthContext.jsx]"]
  node_auth_routes["Auth routes<br/>[auth-routes.js]"]
  node_auth_controller["Auth controller<br/>[AuthController.js]"]
  node_auth_service["Auth service<br/>[AuthService.js]"]
  node_google_service["Google auth service"]
  node_user_store[("Users<br/>[User.js]")]
end

subgraph group_api["API orchestration"]
  node_api_app["Express app<br/>[app.js]"]
  node_dashboard_routes["Dashboard routes"]
  node_dashboard_controller["Dashboard controller"]
  node_dashboard_service["Dashboard service"]
end

subgraph group_finance["Finance domain"]
  node_transaction_ui["Transaction editor"]
  node_transaction_list["Transaction list"]
  node_transaction_routes["Transaction routes"]
  node_transaction_controller["Transaction controller"]
  node_transaction_service["Transaction service"]
  node_transaction_store[("Transactions<br/>[Transaction.js]")]
end

subgraph group_insights["Insights"]
  node_insight_routes["Insight routes<br/>[insight-routes.js]"]
  node_insight_controller["Insight controller"]
  node_insight_service["Insight engine<br/>[InsightService.js]"]
  node_generators["Insight strategies"]
end

node_user(("Finance user"))
node_google["Google OAuth"]
node_mongodb[("MongoDB")]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_auth_ui
node_app -->|"routes to"| node_google_callback
node_app -->|"routes to"| node_dashboard_ui
node_auth_ui -->|"uses"| node_session
node_google_callback -->|"uses"| node_session
node_session -->|"calls"| node_api_client
node_dashboard_ui -->|"requests data"| node_api_client
node_dashboard_ui -->|"renders"| node_charts
node_dashboard_ui -->|"renders"| node_transaction_ui
node_dashboard_ui -->|"renders"| node_transaction_list
node_transaction_ui -->|"submits changes"| node_dashboard_ui
node_transaction_list -->|"sends edit/delete"| node_dashboard_ui
node_api_app -->|"mounts"| node_auth_routes
node_api_app -->|"mounts"| node_transaction_routes
node_api_app -->|"mounts"| node_dashboard_routes
node_api_app -->|"mounts"| node_insight_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_transaction_routes -->|"dispatches"| node_transaction_controller
node_dashboard_routes -->|"dispatches"| node_dashboard_controller
node_insight_routes -->|"dispatches"| node_insight_controller
node_api_app -->|"injects services"| node_auth_controller
node_api_app -->|"injects service"| node_transaction_controller
node_api_app -->|"injects service"| node_dashboard_controller
node_api_app -->|"injects service"| node_insight_controller
node_api_app -->|"creates"| node_auth_service
node_api_app -->|"creates"| node_google_service
node_api_app -->|"creates"| node_transaction_service
node_api_app -->|"creates"| node_dashboard_service
node_api_app -->|"creates"| node_insight_service
node_api_app -->|"provides model"| node_transaction_store
node_api_app -->|"provides model"| node_user_store
node_api_app -.->|"configures OAuth"| node_google
node_api_app -.->|"persists via"| node_mongodb
node_insight_service -.->|"uses strategies"| node_generators
node_auth_service -.->|"reads/writes"| node_user_store
node_google_service -->|"reads/writes"| node_user_store
node_transaction_service -.->|"manages"| node_transaction_store
node_dashboard_service -.->|"summarizes"| node_transaction_store
node_insight_service -.->|"analyzes"| node_transaction_store
node_api_client -.->|"calls auth API"| node_auth_routes
node_api_client -.->|"calls transaction API"| node_transaction_routes
node_api_client -.->|"calls dashboard API"| node_dashboard_routes
node_api_client -.->|"calls insights API"| node_insight_routes

click node_app "https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/app/App.jsx"
click node_auth_ui "https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/features/auth/AuthPage.jsx"
click node_google_callback "https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/features/auth/GoogleCallbackPage.jsx"
click node_session "https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/features/auth/AuthContext.jsx"
click node_api_client "https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/api/client.js"
click node_dashboard_ui "https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/features/dashboard/DashboardPage.jsx"
click node_charts "https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/components/charts/MonthlyTrendChart.jsx"
click node_transaction_ui "https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/components/transactions/TransactionForm.jsx"
click node_transaction_list "https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/components/transactions/TransactionList.jsx"
click node_api_app "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/app.js"
click node_auth_routes "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/routes/auth-routes.js"
click node_transaction_routes "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/routes/transaction-routes.js"
click node_dashboard_routes "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/routes/dashboard-routes.js"
click node_insight_routes "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/routes/insight-routes.js"
click node_auth_controller "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/controllers/AuthController.js"
click node_transaction_controller "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/controllers/TransactionController.js"
click node_dashboard_controller "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/controllers/DashboardController.js"
click node_insight_controller "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/controllers/InsightController.js"
click node_auth_service "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/services/AuthService.js"
click node_google_service "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/services/googleAuthService.js"
click node_transaction_service "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/services/TransactionService.js"
click node_dashboard_service "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/services/DashboardService.js"
click node_insight_service "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/services/InsightService.js"
click node_generators "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/services/insightGenerators.js"
click node_transaction_store "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/models/Transaction.js"
click node_user_store "https://github.com/muuhesham/finance-tracker/blob/main/backend/src/models/User.js"

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_api_client,node_dashboard_ui,node_charts,node_user toneBlue
class node_auth_ui,node_google_callback,node_session,node_auth_routes,node_auth_controller,node_auth_service,node_google_service,node_user_store,node_mongodb toneAmber
class node_api_app,node_dashboard_routes,node_dashboard_controller,node_dashboard_service toneMint
class node_transaction_ui,node_transaction_list,node_transaction_routes,node_transaction_controller,node_transaction_service,node_transaction_store toneRose
class node_insight_routes,node_insight_controller,node_insight_service,node_generators,node_google toneIndigo
```

## Components

### Web experience

- [App routing](https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/app/App.jsx): `frontend/src/app/App.jsx`
- [API client](https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Monthly dashboard](https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/features/dashboard/DashboardPage.jsx): `frontend/src/features/dashboard/DashboardPage.jsx`
- [Dashboard charts](https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/components/charts/MonthlyTrendChart.jsx): `frontend/src/components/charts/MonthlyTrendChart.jsx`

### Identity

- [Sign-in UI](https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/features/auth/AuthPage.jsx): `frontend/src/features/auth/AuthPage.jsx`
- [OAuth callback UI](https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/features/auth/GoogleCallbackPage.jsx): `frontend/src/features/auth/GoogleCallbackPage.jsx`
- [Session context](https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/features/auth/AuthContext.jsx): `frontend/src/features/auth/AuthContext.jsx`
- [Auth routes](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/routes/auth-routes.js): `backend/src/routes/auth-routes.js`
- [Auth controller](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/controllers/AuthController.js): `backend/src/controllers/AuthController.js`
- [Auth service](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/services/AuthService.js): `backend/src/services/AuthService.js`
- [Google auth service](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/services/googleAuthService.js): `backend/src/services/googleAuthService.js`
- [Users](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/models/User.js): `backend/src/models/User.js`

### API orchestration

- [Express app](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/app.js): `backend/src/app.js`
- [Dashboard routes](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/routes/dashboard-routes.js): `backend/src/routes/dashboard-routes.js`
- [Dashboard controller](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/controllers/DashboardController.js): `backend/src/controllers/DashboardController.js`
- [Dashboard service](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/services/DashboardService.js): `backend/src/services/DashboardService.js`

### Finance domain

- [Transaction editor](https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/components/transactions/TransactionForm.jsx): `frontend/src/components/transactions/TransactionForm.jsx`
- [Transaction list](https://github.com/muuhesham/finance-tracker/blob/main/frontend/src/components/transactions/TransactionList.jsx): `frontend/src/components/transactions/TransactionList.jsx`
- [Transaction routes](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/routes/transaction-routes.js): `backend/src/routes/transaction-routes.js`
- [Transaction controller](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/controllers/TransactionController.js): `backend/src/controllers/TransactionController.js`
- [Transaction service](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/services/TransactionService.js): `backend/src/services/TransactionService.js`
- [Transactions](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/models/Transaction.js): `backend/src/models/Transaction.js`

### Insights

- [Insight routes](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/routes/insight-routes.js): `backend/src/routes/insight-routes.js`
- [Insight controller](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/controllers/InsightController.js): `backend/src/controllers/InsightController.js`
- [Insight engine](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/services/InsightService.js): `backend/src/services/InsightService.js`
- [Insight strategies](https://github.com/muuhesham/finance-tracker/blob/main/backend/src/services/insightGenerators.js): `backend/src/services/insightGenerators.js`

### Other components

- **Finance user**
- **Google OAuth**
- **MongoDB**

## Connections

- Finance user → App routing: uses (evidence: `frontend/src/app/App.jsx`)
- App routing → Sign-in UI: routes to (evidence: `frontend/src/app/App.jsx`)
- App routing → OAuth callback UI: routes to (evidence: `frontend/src/app/App.jsx`)
- App routing → Monthly dashboard: routes to (evidence: `frontend/src/app/App.jsx`)
- Sign-in UI → Session context: uses (evidence: `frontend/src/features/auth/AuthPage.jsx`)
- OAuth callback UI → Session context: uses (evidence: `frontend/src/features/auth/GoogleCallbackPage.jsx`)
- Session context → API client: calls (evidence: `frontend/src/features/auth/AuthContext.jsx`)
- Monthly dashboard → API client: requests data (evidence: `frontend/src/features/dashboard/DashboardPage.jsx`)
- Monthly dashboard → Dashboard charts: renders (evidence: `frontend/src/features/dashboard/DashboardPage.jsx`)
- Monthly dashboard → Transaction editor: renders (evidence: `frontend/src/features/dashboard/DashboardPage.jsx`)
- Monthly dashboard → Transaction list: renders (evidence: `frontend/src/features/dashboard/DashboardPage.jsx`)
- Transaction editor → Monthly dashboard: submits changes (evidence: `frontend/src/features/dashboard/DashboardPage.jsx`)
- Transaction list → Monthly dashboard: sends edit/delete (evidence: `frontend/src/features/dashboard/DashboardPage.jsx`)
- Express app → Auth routes: mounts (evidence: `backend/src/app.js`)
- Express app → Transaction routes: mounts (evidence: `backend/src/app.js`)
- Express app → Dashboard routes: mounts (evidence: `backend/src/app.js`)
- Express app → Insight routes: mounts (evidence: `backend/src/app.js`)
- Auth routes → Auth controller: dispatches (evidence: `backend/src/routes/auth-routes.js`)
- Transaction routes → Transaction controller: dispatches (evidence: `backend/src/routes/transaction-routes.js`)
- Dashboard routes → Dashboard controller: dispatches (evidence: `backend/src/routes/dashboard-routes.js`)
- Insight routes → Insight controller: dispatches (evidence: `backend/src/routes/insight-routes.js`)
- Express app → Auth controller: injects services (evidence: `backend/src/app.js`)
- Express app → Transaction controller: injects service (evidence: `backend/src/app.js`)
- Express app → Dashboard controller: injects service (evidence: `backend/src/app.js`)
- Express app → Insight controller: injects service (evidence: `backend/src/app.js`)
- Express app → Auth service: creates (evidence: `backend/src/app.js`)
- Express app → Google auth service: creates (evidence: `backend/src/app.js`)
- Express app → Transaction service: creates (evidence: `backend/src/app.js`)
- Express app → Dashboard service: creates (evidence: `backend/src/app.js`)
- Express app → Insight engine: creates (evidence: `backend/src/app.js`)
- Express app → Transactions: provides model (evidence: `backend/src/app.js`)
- Express app → Users: provides model (evidence: `backend/src/app.js`)
- Express app → Google OAuth: configures OAuth
- Express app → MongoDB: persists via
- Insight engine → Insight strategies: uses strategies
- Auth service → Users: reads/writes
- Google auth service → Users: reads/writes (evidence: `backend/src/services/googleAuthService.js`)
- Transaction service → Transactions: manages
- Dashboard service → Transactions: summarizes
- Insight engine → Transactions: analyzes
- API client → Auth routes: calls auth API
- API client → Transaction routes: calls transaction API
- API client → Dashboard routes: calls dashboard API
- API client → Insight routes: calls insights API