# achinthasampath/ai_powered_finance_tracker architecture

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

- Interactive diagram: https://gitdiagram.com/achinthasampath/ai_powered_finance_tracker
- Repository: https://github.com/achinthasampath/ai_powered_finance_tracker

## Overview

Expense Tracker lets users record income and expenses, import CSV bank statements for AI categorization, and review balances, spending breakdowns, and transaction history. The browser routes users to dashboard, entry, and history views; those views call a shared HTTP service, which reaches Express routes and transaction controllers. Controllers validate, summarize, and persist records through the transaction model, while statement imports invoke Gemini before bulk insertion. The README documents search/filter and dark mode; source excerpts are partial, so some view behavior and integrations are represented at their documented subsystem level.

Main entry points: [`frontend/src/App.jsx`](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/App.jsx) (App routing), [`frontend/src/services/transactionService.js`](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/services/transactionService.js) (HTTP service), [`frontend/src/pages/Dashboard.jsx`](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/pages/Dashboard.jsx) (Dashboard), [`backend/server.js`](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/server.js) (Express server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["App routing<br/>[App.jsx]"]
  node_navbar["Navigation<br/>[Navbar.jsx]"]
  node_theme["Theme state<br/>[ThemeContext.jsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_add["Add transaction<br/>[Add.jsx]"]
  node_history["Transaction history<br/>[Transactions.jsx]"]
  node_uploadui["CSV upload UI<br/>[FileUpload.jsx]"]
  node_client["HTTP service"]
end

subgraph group_api["Transaction API"]
  node_server["Express server<br/>[server.js]"]
  node_routes["API routes"]
  node_controller["Transaction operations"]
end

subgraph group_data["Persistence"]
  node_model["Transaction model<br/>[transactions.js]"]
  node_dbconfig["DB connection<br/>[db.js]"]
end

subgraph group_imports["Statement import"]
  node_upload["File parser middleware<br/>[upload.js]"]
  node_gemini["AI categorization<br/>[geminiService.js]"]
end

node_user(("User"))
node_mongo[("MongoDB")]
node_googleai{{"Gemini API"}}

node_user -->|"uses"| node_app
node_app -->|"renders"| node_navbar
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_add
node_app -->|"routes to"| node_history
node_app -->|"provides"| node_theme
node_navbar -->|"updates"| node_theme
node_dashboard -->|"fetches data"| node_client
node_dashboard -->|"renders"| node_uploadui
node_add -->|"submits transaction"| node_client
node_history -->|"manages records"| node_client
node_uploadui -->|"uploads CSV"| node_client
node_client -->|"sends HTTP requests"| node_server
node_server -->|"connects database"| node_dbconfig
node_server -->|"mounts routes"| node_routes
node_routes -->|"dispatches"| node_controller
node_routes -->|"parses upload"| node_upload
node_controller -->|"reads and writes"| node_model
node_controller -->|"categorizes CSV"| node_gemini
node_gemini -->|"requests categorization"| node_googleai
node_dbconfig -->|"connects"| node_mongo
node_model -.->|"persists records"| node_mongo

click node_app "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/App.jsx"
click node_navbar "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/components/Navbar.jsx"
click node_theme "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/context/ThemeContext.jsx"
click node_dashboard "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/pages/Dashboard.jsx"
click node_add "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/pages/Add.jsx"
click node_history "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/pages/Transactions.jsx"
click node_uploadui "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/components/FileUpload.jsx"
click node_client "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/services/transactionService.js"
click node_server "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/server.js"
click node_routes "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/src/routes/transactionRoutes.js"
click node_controller "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/src/controllers/transactionController.js"
click node_upload "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/src/middleware/upload.js"
click node_gemini "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/src/services/geminiService.js"
click node_model "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/src/models/transactions.js"
click node_dbconfig "https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/src/config/db.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_navbar,node_theme,node_dashboard,node_add,node_history,node_uploadui,node_client,node_user toneBlue
class node_server,node_routes,node_controller,node_mongo toneAmber
class node_model,node_dbconfig,node_googleai toneMint
class node_upload,node_gemini toneRose
```

## Components

### Web application

- [App routing](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Navigation](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/components/Navbar.jsx): `frontend/src/components/Navbar.jsx`
- [Theme state](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/context/ThemeContext.jsx): `frontend/src/context/ThemeContext.jsx`
- [Dashboard](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Add transaction](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/pages/Add.jsx): `frontend/src/pages/Add.jsx`
- [Transaction history](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/pages/Transactions.jsx): `frontend/src/pages/Transactions.jsx`
- [CSV upload UI](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/components/FileUpload.jsx): `frontend/src/components/FileUpload.jsx`
- [HTTP service](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/frontend/src/services/transactionService.js): `frontend/src/services/transactionService.js`

### Transaction API

- [Express server](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/server.js): `backend/server.js`
- [API routes](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/src/routes/transactionRoutes.js): `backend/src/routes/transactionRoutes.js`
- [Transaction operations](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/src/controllers/transactionController.js): `backend/src/controllers/transactionController.js`

### Persistence

- [Transaction model](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/src/models/transactions.js): `backend/src/models/transactions.js`
- [DB connection](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/src/config/db.js): `backend/src/config/db.js`

### Statement import

- [File parser middleware](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/src/middleware/upload.js): `backend/src/middleware/upload.js`
- [AI categorization](https://github.com/achinthasampath/ai_powered_finance_tracker/blob/main/backend/src/services/geminiService.js): `backend/src/services/geminiService.js`

### Other components

- **User**
- **MongoDB**
- **Gemini API**

## Connections

- User → App routing: uses (evidence: `README.md`)
- App routing → Navigation: renders (evidence: `frontend/src/App.jsx`)
- App routing → Dashboard: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Add transaction: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Transaction history: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Theme state: provides (evidence: `frontend/src/App.jsx`)
- Navigation → Theme state: updates (evidence: `frontend/src/components/Navbar.jsx`)
- Dashboard → HTTP service: fetches data (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → CSV upload UI: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Add transaction → HTTP service: submits transaction (evidence: `frontend/src/pages/Add.jsx`)
- Transaction history → HTTP service: manages records (evidence: `frontend/src/pages/Transactions.jsx`)
- CSV upload UI → HTTP service: uploads CSV (evidence: `frontend/src/components/FileUpload.jsx`)
- HTTP service → Express server: sends HTTP requests (evidence: `frontend/src/services/transactionService.js`)
- Express server → DB connection: connects database (evidence: `backend/server.js`)
- Express server → API routes: mounts routes (evidence: `backend/server.js`)
- API routes → Transaction operations: dispatches (evidence: `backend/src/routes/transactionRoutes.js`)
- API routes → File parser middleware: parses upload (evidence: `backend/src/routes/transactionRoutes.js`)
- Transaction operations → Transaction model: reads and writes (evidence: `backend/src/controllers/transactionController.js`)
- Transaction operations → AI categorization: categorizes CSV (evidence: `backend/src/controllers/transactionController.js`)
- AI categorization → Gemini API: requests categorization (evidence: `backend/src/services/geminiService.js`)
- DB connection → MongoDB: connects (evidence: `backend/src/config/db.js`)
- Transaction model → MongoDB: persists records
