# neeraj966/finstreet architecture

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

- Interactive diagram: https://gitdiagram.com/neeraj966/finstreet
- Repository: https://github.com/neeraj966/finstreet

## Overview

#### Purpose and Runtime Shape
FinStreet is a two-process personal-finance system: a React/Vite browser client and a Node.js/Express REST API backed by MongoDB. It manages authenticated users’ expenses, budgets, recurring transactions, Paytm statement imports, account credits, reports, investments, events, and advice.

Entry points are `Frontend/src/main.jsx` and `Frontend/src/App.jsx` for the client, and `Backend/src/index.js` plus `Backend/src/app.js` for API startup and HTTP composition.

#### Client Application and Navigation
The frontend is a React single-page application with route-level finance modules. Core user state, including authenticated-user access, is centralized in `Frontend/src/context/UserContext.jsx`; shared navigation and authentication UI live in `Frontend/src/componants/Navbar.jsx` and `Frontend/src/componants/GoogleAuthButton.jsx`.

Primary feature screens are implemented as page components:
- Expenses/import/report workflow: `Frontend/src/pages/Expenses.jsx`
- Budget planning and status: `Frontend/src/pages/Budget.jsx`
- Dashboard aggregate views: `Frontend/src/pages/Dashboard.jsx`
- Account-credit history: `Frontend/src/pages/MainAccount.jsx`

The frontend targets the backend through `VITE_BASE_URL`; it does not host business persistence itself.

#### API Composition and Security Boundary
Express application setup, cross-origin behavior, middleware, and route registration are concentrated in `Backend/src/app.js`. `Backend/src/index.js` starts the service after database setup from `Backend/src/DB/index.js`.

API domains are exposed through dedicated route modules, notably:
- `Backend/src/routes/User.route.js`
- `Backend/src/routes/Expense.route.js`
- `Backend/src/routes/Budget.route.js`
- `Backend/src/routes/Investment.route.js`
- `Backend/src/routes/Event.route.js`
- `Backend/src/routes/Advisor.route.js`

JWT-based identity protection is the principal API boundary in `Backend/src/middleware/auth.middleware.js`. User session/token invalidation state is represented by `Backend/src/models/Blacklist.model.js`.

#### Finance Persistence Model
Mongoose models form the system of record in MongoDB. Expense records, including manually created and imported/recurring entries, are held in `Backend/src/models/Expanse.model.js`; category-period budgets are in `Backend/src/models/Budget.model.js`; users and main-account-related state are in `Backend/src/models/User.model.js`.

Controllers implement the API’s feature orchestration and aggregate rules:
- `Backend/src/controller/Expense.Controller.js`
- `Backend/src/controller/Budget.Controller.js`
- `Backend/src/controller/User.Controller.js`

Expense categories are shared domain vocabulary across backend operations through `Backend/src/constants/categories.js`, with a corresponding frontend set in `Frontend/src/constants/categories.js`.

#### Expense, Budget, and Recurrence Flow
Users create, query, edit, and delete expenses through the Expenses page to the expense API/controller, which persists records in MongoDB. Budget operations use the same category model, allowing budget progress, alerts, and dashboard calculations to compare category spending against monthly allocations.

Recurring monthly expenses are a backend concern implemented in `Backend/src/utills/RecurringExpenses.js`; generated records re-enter the normal expense persistence and reporting path rather than creating a separate transaction type.

#### Paytm Import and Reporting Boundary
Statement imports cross a file-processing boundary: uploaded/generated files reside under `Backend/public/imports/`, are parsed by `Backend/src/utills/PaytmPassbook.js`, and can also be run through `Backend/scripts/importPaytmPassbook.js`. The import flow maps paid rows into expense records and received rows into the user’s main-account history while suppressing duplicates.

Client-side downloadable report generation is isolated in `Frontend/src/utils/reportExports.js`, producing CSV/PDF from the data currently returned by API filters; it does not require a separate report service.

#### Supporting Finance Modules
Investments, events, and advice are independent API domains with separate controllers and models where applicable: `Backend/src/controller/Investment.Controller.js`, `Backend/src/models/Investment.model.js`, `Backend/src/controller/Event.Controller.js`, and `Backend/src/models/Event.model.js`. Their corresponding client pages extend the SPA without changing the core expense-budget-account flow.

External material dependencies are MongoDB/Mongoose for persistence, JWT for authentication, Multer and SheetJS for spreadsheet ingestion, and jsPDF-based frontend exports.

Main entry points: [`Backend/src/app.js`](https://github.com/neeraj966/finstreet/blob/main/Backend/src/app.js) (Express app), [`Frontend/src/main.jsx`](https://github.com/neeraj966/finstreet/blob/main/Frontend/src/main.jsx) (SPA entry & routes), [`Backend/src/controller/Expense.Controller.js`](https://github.com/neeraj966/finstreet/blob/main/Backend/src/controller/Expense.Controller.js) (Expense API), [`Backend/src/DB/index.js`](https://github.com/neeraj966/finstreet/blob/main/Backend/src/DB/index.js) (MongoDB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_client_entry["SPA entry &amp; routes<br/>React/Vite<br/>[main.jsx]"]
  node_user_context["User context<br/>React context<br/>[UserContext.jsx]"]
  node_auth_ui["Navigation &amp; Google auth<br/>shared UI"]
  node_expense_page["Expenses &amp; reports<br/>page<br/>[Expenses.jsx]"]
  node_budget_page["Budget planning<br/>page<br/>[Budget.jsx]"]
  node_dashboard_page["Dashboard<br/>page<br/>[Dashboard.jsx]"]
  node_account_page["Main account<br/>page<br/>[MainAccount.jsx]"]
  node_report_exports["CSV/PDF exports<br/>client export<br/>[reportExports.js]"]
end

subgraph group_api["Express API"]
  node_server_entry["API startup<br/>Node entry<br/>[index.js]"]
  node_express_app["Express app<br/>HTTP composition<br/>[app.js]"]
  node_auth_middleware["JWT protection<br/>auth middleware<br/>[auth.middleware.js]"]
  node_blacklist["Token blacklist<br/>Mongoose model<br/>[Blacklist.model.js]"]
end

subgraph group_finance["Finance Domains"]
  node_expense_api["Expense API<br/>route/controller"]
  node_budget_api["Budget API<br/>route/controller"]
  node_user_api["User &amp; account API<br/>route/controller<br/>[User.Controller.js]"]
  node_supporting_apis["Investments, events &amp; advice<br/>API domains"]
  node_categories["Expense categories<br/>domain constants<br/>[categories.js]"]
  node_recurring_expenses["Recurring expense generator<br/>backend job"]
end

subgraph group_imports["Import Pipeline"]
  node_paytm_parser["Paytm statement parser<br/>file ingestion<br/>[PaytmPassbook.js]"]
  node_import_files["Statement files<br/>uploads"]
  node_import_script["Paytm import script"]
end

node_mongodb[("MongoDB<br/>system of record<br/>[index.js]")]

node_client_entry -->|"provides user state"| node_user_context
node_client_entry -->|"renders"| node_auth_ui
node_client_entry -->|"routes to"| node_expense_page
node_client_entry -->|"routes to"| node_budget_page
node_client_entry -->|"routes to"| node_dashboard_page
node_client_entry -->|"routes to"| node_account_page
node_expense_page -->|"exports filtered data"| node_report_exports
node_expense_page -->|"REST via VITE_BASE_URL"| node_express_app
node_budget_page -->|"REST"| node_express_app
node_dashboard_page -->|"REST aggregates"| node_express_app
node_account_page -->|"REST"| node_express_app
node_server_entry -->|"starts"| node_express_app
node_server_entry -->|"connects"| node_mongodb
node_express_app -->|"protects routes"| node_auth_middleware
node_auth_middleware -->|"checks invalidation"| node_blacklist
node_express_app -->|"expense routes"| node_expense_api
node_express_app -->|"budget routes"| node_budget_api
node_express_app -->|"user routes"| node_user_api
node_express_app -->|"supporting routes"| node_supporting_apis
node_expense_api -->|"expense records"| node_mongodb
node_budget_api -->|"budget records"| node_mongodb
node_user_api -->|"users and account history"| node_mongodb
node_supporting_apis -->|"domain data"| node_mongodb
node_expense_api -->|"uses"| node_categories
node_budget_api -->|"compares spending"| node_categories
node_recurring_expenses -->|"creates expenses"| node_expense_api
node_import_files -->|"parsed by"| node_paytm_parser
node_import_script -->|"runs"| node_paytm_parser
node_paytm_parser -->|"paid rows"| node_expense_api
node_paytm_parser -->|"received rows"| node_user_api

click node_client_entry "https://github.com/neeraj966/finstreet/blob/main/Frontend/src/main.jsx"
click node_user_context "https://github.com/neeraj966/finstreet/blob/main/Frontend/src/context/UserContext.jsx"
click node_auth_ui "https://github.com/neeraj966/finstreet/blob/main/Frontend/src/componants/GoogleAuthButton.jsx"
click node_expense_page "https://github.com/neeraj966/finstreet/blob/main/Frontend/src/pages/Expenses.jsx"
click node_budget_page "https://github.com/neeraj966/finstreet/blob/main/Frontend/src/pages/Budget.jsx"
click node_dashboard_page "https://github.com/neeraj966/finstreet/blob/main/Frontend/src/pages/Dashboard.jsx"
click node_account_page "https://github.com/neeraj966/finstreet/blob/main/Frontend/src/pages/MainAccount.jsx"
click node_report_exports "https://github.com/neeraj966/finstreet/blob/main/Frontend/src/utils/reportExports.js"
click node_server_entry "https://github.com/neeraj966/finstreet/blob/main/Backend/src/index.js"
click node_express_app "https://github.com/neeraj966/finstreet/blob/main/Backend/src/app.js"
click node_auth_middleware "https://github.com/neeraj966/finstreet/blob/main/Backend/src/middleware/auth.middleware.js"
click node_expense_api "https://github.com/neeraj966/finstreet/blob/main/Backend/src/controller/Expense.Controller.js"
click node_budget_api "https://github.com/neeraj966/finstreet/blob/main/Backend/src/controller/Budget.Controller.js"
click node_user_api "https://github.com/neeraj966/finstreet/blob/main/Backend/src/controller/User.Controller.js"
click node_supporting_apis "https://github.com/neeraj966/finstreet/blob/main/Backend/src/routes/Investment.route.js"
click node_categories "https://github.com/neeraj966/finstreet/blob/main/Backend/src/constants/categories.js"
click node_recurring_expenses "https://github.com/neeraj966/finstreet/blob/main/Backend/src/utills/RecurringExpenses.js"
click node_paytm_parser "https://github.com/neeraj966/finstreet/blob/main/Backend/src/utills/PaytmPassbook.js"
click node_import_script "https://github.com/neeraj966/finstreet/blob/main/Backend/scripts/importPaytmPassbook.js"
click node_mongodb "https://github.com/neeraj966/finstreet/blob/main/Backend/src/DB/index.js"
click node_blacklist "https://github.com/neeraj966/finstreet/blob/main/Backend/src/models/Blacklist.model.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_client_entry,node_user_context,node_auth_ui,node_expense_page,node_budget_page,node_dashboard_page,node_account_page,node_report_exports toneBlue
class node_server_entry,node_express_app,node_auth_middleware,node_blacklist toneAmber
class node_expense_api,node_budget_api,node_user_api,node_supporting_apis,node_categories,node_recurring_expenses toneMint
class node_paytm_parser,node_import_files,node_import_script toneRose
class node_mongodb toneNeutral
```

## Components

### React Client

- [SPA entry & routes](https://github.com/neeraj966/finstreet/blob/main/Frontend/src/main.jsx): React/Vite · `Frontend/src/main.jsx`
- [User context](https://github.com/neeraj966/finstreet/blob/main/Frontend/src/context/UserContext.jsx): React context · Central authenticated-user state. · `Frontend/src/context/UserContext.jsx`
- [Navigation & Google auth](https://github.com/neeraj966/finstreet/blob/main/Frontend/src/componants/GoogleAuthButton.jsx): shared UI · `Frontend/src/componants/GoogleAuthButton.jsx`
- [Expenses & reports](https://github.com/neeraj966/finstreet/blob/main/Frontend/src/pages/Expenses.jsx): page · Expense management, import, and report workflow. · `Frontend/src/pages/Expenses.jsx`
- [Budget planning](https://github.com/neeraj966/finstreet/blob/main/Frontend/src/pages/Budget.jsx): page · `Frontend/src/pages/Budget.jsx`
- [Dashboard](https://github.com/neeraj966/finstreet/blob/main/Frontend/src/pages/Dashboard.jsx): page · `Frontend/src/pages/Dashboard.jsx`
- [Main account](https://github.com/neeraj966/finstreet/blob/main/Frontend/src/pages/MainAccount.jsx): page · `Frontend/src/pages/MainAccount.jsx`
- [CSV/PDF exports](https://github.com/neeraj966/finstreet/blob/main/Frontend/src/utils/reportExports.js): client export · Exports API-filtered client data. · `Frontend/src/utils/reportExports.js`

### Express API

- [API startup](https://github.com/neeraj966/finstreet/blob/main/Backend/src/index.js): Node entry · Connects the database and starts Express. · `Backend/src/index.js`
- [Express app](https://github.com/neeraj966/finstreet/blob/main/Backend/src/app.js): HTTP composition · CORS, middleware, and route registration. · `Backend/src/app.js`
- [JWT protection](https://github.com/neeraj966/finstreet/blob/main/Backend/src/middleware/auth.middleware.js): auth middleware · `Backend/src/middleware/auth.middleware.js`
- [Token blacklist](https://github.com/neeraj966/finstreet/blob/main/Backend/src/models/Blacklist.model.js): Mongoose model · Tracks invalidated sessions or tokens. · `Backend/src/models/Blacklist.model.js`

### Finance Domains

- [Expense API](https://github.com/neeraj966/finstreet/blob/main/Backend/src/controller/Expense.Controller.js): route/controller · `Backend/src/controller/Expense.Controller.js`
- [Budget API](https://github.com/neeraj966/finstreet/blob/main/Backend/src/controller/Budget.Controller.js): route/controller · `Backend/src/controller/Budget.Controller.js`
- [User & account API](https://github.com/neeraj966/finstreet/blob/main/Backend/src/controller/User.Controller.js): route/controller · `Backend/src/controller/User.Controller.js`
- [Investments, events & advice](https://github.com/neeraj966/finstreet/blob/main/Backend/src/routes/Investment.route.js): API domains · Independent supporting finance modules. · `Backend/src/routes/Investment.route.js`
- [Expense categories](https://github.com/neeraj966/finstreet/blob/main/Backend/src/constants/categories.js): domain constants · Shared vocabulary for expenses and budgets. · `Backend/src/constants/categories.js`
- [Recurring expense generator](https://github.com/neeraj966/finstreet/blob/main/Backend/src/utills/RecurringExpenses.js): backend job · Creates normal monthly expense records. · `Backend/src/utills/RecurringExpenses.js`

### Import Pipeline

- [Paytm statement parser](https://github.com/neeraj966/finstreet/blob/main/Backend/src/utills/PaytmPassbook.js): file ingestion · Maps paid rows to expenses and received rows to accounts. · `Backend/src/utills/PaytmPassbook.js`
- **Statement files**: uploads
- [Paytm import script](https://github.com/neeraj966/finstreet/blob/main/Backend/scripts/importPaytmPassbook.js): script · `Backend/scripts/importPaytmPassbook.js`

### Other components

- [MongoDB](https://github.com/neeraj966/finstreet/blob/main/Backend/src/DB/index.js): system of record · Mongoose-backed finance and identity data. · `Backend/src/DB/index.js`

## Connections

- SPA entry & routes → User context: provides user state
- SPA entry & routes → Navigation & Google auth: renders
- SPA entry & routes → Expenses & reports: routes to
- SPA entry & routes → Budget planning: routes to
- SPA entry & routes → Dashboard: routes to
- SPA entry & routes → Main account: routes to
- Expenses & reports → CSV/PDF exports: exports filtered data
- Expenses & reports → Express app: REST via VITE_BASE_URL
- Budget planning → Express app: REST
- Dashboard → Express app: REST aggregates
- Main account → Express app: REST
- API startup → Express app: starts
- API startup → MongoDB: connects
- Express app → JWT protection: protects routes
- JWT protection → Token blacklist: checks invalidation
- Express app → Expense API: expense routes
- Express app → Budget API: budget routes
- Express app → User & account API: user routes
- Express app → Investments, events & advice: supporting routes
- Expense API → MongoDB: expense records
- Budget API → MongoDB: budget records
- User & account API → MongoDB: users and account history
- Investments, events & advice → MongoDB: domain data
- Expense API → Expense categories: uses
- Budget API → Expense categories: compares spending
- Recurring expense generator → Expense API: creates expenses
- Statement files → Paytm statement parser: parsed by
- Paytm import script → Paytm statement parser: runs
- Paytm statement parser → Expense API: paid rows
- Paytm statement parser → User & account API: received rows