# digvijaynarayanpandey/expense-tracker-app architecture

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

- Interactive diagram: https://gitdiagram.com/digvijaynarayanpandey/expense-tracker-app
- Repository: https://github.com/digvijaynarayanpandey/expense-tracker-app

## Overview

1. **Repo shape**
   This is a two-app monorepo: a React/Vite frontend in `frontend/` and an Express/Mongoose backend in `backend/`. The backend exposes a REST API; the frontend is a single-page app that consumes it over HTTP.

2. **Top-level product boundary**
   The application centers on personal finance tracking for one authenticated user. Core domain objects are `User`, `Income`, and `Expense`, with the dashboard acting as the read-model that aggregates those records into charts, summary cards, and recent-activity lists.

3. **Frontend presentation layer**
   `frontend/src/pages/` defines route-level screens for landing, auth, dashboard home, income, expense, guides, policy pages, and 404. `components/` holds reusable UI blocks for cards, charts, forms, modals, navigation, and alerts. This is a classic page/layout/component split.

4. **Frontend app shell and state**
   `App.jsx` and `main.jsx` bootstrap routing and the React tree. `context/UserContext.jsx` plus `hooks/useUserAuth.jsx` manage session-aware user state. `ThemeContext` suggests a UI preference boundary, separate from auth and data state.

5. **Frontend-to-backend integration**
   `utils/axiosInstance.js` and `utils/apiPaths.js` centralize API calls. The client stores the JWT locally and attaches it to requests through the axios layer. The frontend depends on this to access protected routes like dashboard, income, expense, and profile endpoints.

6. **Backend API surface**
   The Express app is split by resource: `authRoutes`, `dashboardRoutes`, `incomeRoutes`, and `expenseRoutes`. Controllers implement the business logic for registration/login, profile image updates, aggregate dashboard data, CRUD for income/expense, and Excel export endpoints.

7. **Authentication and authorization flow**
   `authController` issues JWTs after login and likely hashes passwords through the `User` model layer or controller logic. `authMiddleware` protects all finance and profile routes by verifying the bearer token and attaching the authenticated user to the request context. Ownership checks prevent users from deleting records they do not own.

8. **Persistence layer**
   `config/db.js` connects to MongoDB via Mongoose. The schema boundary is simple: `User` stores credentials and profile image URL, while `Income` and `Expense` store user-scoped financial transactions with date, amount, label/category, and emoji icon. This makes MongoDB the system of record for all finance data.

9. **File upload boundary**
   `middleware/uploadMiddle.js` handles multipart uploads for profile photos. Uploaded images are stored in the backend’s `uploads/` area, then their URL is saved back to the user record. This is a separate flow from normal JSON-based CRUD.

10. **Reporting and aggregation**
    `dashboardController` computes cross-collection summaries such as total balance, total income, total expense, recent transactions, and time-windowed trends. The frontend dashboard components then render those aggregates into pie, bar, and line charts via Recharts.

11. **Transaction workflows**
    Income and expense pages use modal-based forms, emoji pickers, and list views for create/read/delete interactions. Each transaction type has its own overview component, indicating separate UX and API paths even though they share the same conceptual pattern.

12. **Export and offline artifacts**
    The backend includes Excel generation via `xlsx` for both income and expense exports. Those downloads are initiated from the frontend as file responses, so report generation is server-side rather than client-side.

13. **Static/public and deployment concerns**
    The frontend includes `public/` assets like `robots.txt`, `sitemap.xml`, and a verification HTML file, which suggests SEO and site verification are part of the deployed SPA. `frontend/vercel.json` indicates frontend hosting/deployment configuration is treated separately from the backend runtime.

14. **Architecture diagram takeaway**
    The clean diagram should show: browser SPA → axios-based REST calls → Express controllers/middleware → Mongoose models → MongoDB, with a side branch for image upload storage and another for Excel file downloads. The key boundaries are auth, transaction CRUD, dashboard aggregation, and profile media handling.

Main entry points: [`frontend/src/components`](https://github.com/digvijaynarayanpandey/expense-tracker-app/tree/main/frontend/src/components) (UI blocks), [`backend/routes`](https://github.com/digvijaynarayanpandey/expense-tracker-app/tree/main/backend/routes) (API routes), [`backend/controllers/dashboardController.js`](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/controllers/dashboardController.js) (Dashboard agg), [`backend/controllers/authController.js`](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/controllers/authController.js) (Auth flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_bootstrap["App shell<br/>spa bootstrap<br/>[main.jsx]"]
  node_fe_routes["Route pages<br/>page layer"]
  node_fe_layouts["Layouts"]
  node_fe_components["UI blocks<br/>presentational components"]
  node_fe_state(("User state<br/>client state"))
  node_fe_theme(("Theme state<br/>ui preference<br/>[ThemeContext.jsx]"))
  node_fe_api["API client<br/>http integration<br/>[axiosInstance.js]"]
  node_fe_upload["Image upload<br/>client upload helper<br/>[uploadImage.js]"]
end

subgraph group_backend["Backend"]
  node_be_server["API server<br/>express app<br/>[server.js]"]
  node_be_routes["API routes<br/>rest routes"]
  node_be_auth["Auth flow<br/>controller<br/>[authController.js]"]
  node_be_dashboard["Dashboard agg<br/>controller"]
  node_be_income["Income CRUD<br/>controller"]
  node_be_expense["Expense CRUD<br/>controller"]
  node_be_authmw["Auth guard<br/>middleware<br/>[authMiddleware.js]"]
  node_be_uploadmw["Upload middleware<br/>multipart middleware<br/>[uploadMiddle.js]"]
  node_be_db[("MongoDB<br/>database connection<br/>[db.js]")]
  node_be_user["User model<br/>mongoose model<br/>[User.js]"]
  node_be_income_model["Income model<br/>mongoose model<br/>[Income.js]"]
  node_be_expense_model["Expense model<br/>mongoose model<br/>[Expense.js]"]
end

node_fe_bootstrap -->|"renders"| node_fe_routes
node_fe_bootstrap -->|"wraps"| node_fe_layouts
node_fe_routes -->|"composes"| node_fe_components
node_fe_layouts -->|"reads"| node_fe_state
node_fe_state -->|"calls"| node_fe_api
node_fe_components -->|"calls"| node_fe_api
node_fe_upload -->|"uses"| node_fe_api
node_fe_state -.->|"separates"| node_fe_theme
node_fe_api -->|"HTTP"| node_be_server
node_be_server -->|"mounts"| node_be_routes
node_be_routes -->|"dispatches"| node_be_auth
node_be_routes -->|"dispatches"| node_be_dashboard
node_be_routes -->|"dispatches"| node_be_income
node_be_routes -->|"dispatches"| node_be_expense
node_be_auth -->|"protected by"| node_be_authmw
node_be_dashboard -->|"protected by"| node_be_authmw
node_be_income -->|"protected by"| node_be_authmw
node_be_expense -->|"protected by"| node_be_authmw
node_be_auth -->|"uses"| node_be_uploadmw
node_be_auth -->|"persists"| node_be_user
node_be_dashboard -->|"reads"| node_be_income_model
node_be_dashboard -->|"reads"| node_be_expense_model
node_be_income -->|"persists"| node_be_income_model
node_be_expense -->|"persists"| node_be_expense_model
node_be_user -->|"stored in"| node_be_db
node_be_income_model -->|"stored in"| node_be_db
node_be_expense_model -->|"stored in"| node_be_db
node_fe_components -->|"shows"| node_be_dashboard
node_fe_components -->|"manages"| node_be_income
node_fe_components -->|"manages"| node_be_expense

click node_fe_bootstrap "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/frontend/src/main.jsx"
click node_fe_routes "https://github.com/digvijaynarayanpandey/expense-tracker-app/tree/main/frontend/src/pages"
click node_fe_layouts "https://github.com/digvijaynarayanpandey/expense-tracker-app/tree/main/frontend/src/components/layouts"
click node_fe_components "https://github.com/digvijaynarayanpandey/expense-tracker-app/tree/main/frontend/src/components"
click node_fe_state "https://github.com/digvijaynarayanpandey/expense-tracker-app/tree/main/frontend/src/context"
click node_fe_theme "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/frontend/src/context/ThemeContext.jsx"
click node_fe_api "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/frontend/src/utils/axiosInstance.js"
click node_fe_upload "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/frontend/src/utils/uploadImage.js"
click node_be_server "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/server.js"
click node_be_routes "https://github.com/digvijaynarayanpandey/expense-tracker-app/tree/main/backend/routes"
click node_be_auth "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/controllers/authController.js"
click node_be_dashboard "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/controllers/dashboardController.js"
click node_be_income "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/controllers/incomeController.js"
click node_be_expense "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/controllers/expenseController.js"
click node_be_authmw "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/middleware/authMiddleware.js"
click node_be_uploadmw "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/middleware/uploadMiddle.js"
click node_be_db "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/config/db.js"
click node_be_user "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/models/User.js"
click node_be_income_model "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/models/Income.js"
click node_be_expense_model "https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/models/Expense.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_fe_bootstrap,node_fe_routes,node_fe_layouts,node_fe_components,node_fe_state,node_fe_theme,node_fe_api,node_fe_upload toneBlue
class node_be_server,node_be_routes,node_be_auth,node_be_dashboard,node_be_income,node_be_expense,node_be_authmw,node_be_uploadmw,node_be_db,node_be_user,node_be_income_model,node_be_expense_model toneAmber
```

## Components

### Frontend

React/Vite SPA

- [App shell](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/frontend/src/main.jsx): spa bootstrap · Vite entry and top-level routing · `frontend/src/main.jsx`
- [Route pages](https://github.com/digvijaynarayanpandey/expense-tracker-app/tree/main/frontend/src/pages): page layer · Landing, auth, dashboard, guides, policy and error screens · `frontend/src/pages`
- [Layouts](https://github.com/digvijaynarayanpandey/expense-tracker-app/tree/main/frontend/src/components/layouts): chrome/layouts · Auth and dashboard shells with nav and side menu · `frontend/src/components/layouts`
- [UI blocks](https://github.com/digvijaynarayanpandey/expense-tracker-app/tree/main/frontend/src/components): presentational components · Cards, charts, forms, modals, alerts and reusable inputs · `frontend/src/components`
- [User state](https://github.com/digvijaynarayanpandey/expense-tracker-app/tree/main/frontend/src/context): client state · Auth-aware user context and session hook · `frontend/src/context`
- [Theme state](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/frontend/src/context/ThemeContext.jsx): ui preference · Theme context for visual mode preferences · `frontend/src/context/ThemeContext.jsx`
- [API client](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/frontend/src/utils/axiosInstance.js): http integration · Axios instance and endpoint path helpers · `frontend/src/utils/axiosInstance.js`
- [Image upload](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/frontend/src/utils/uploadImage.js): client upload helper · Frontend helper for profile photo upload flow · `frontend/src/utils/uploadImage.js`

### Backend

Express/Mongoose API

- [API server](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/server.js): express app · Backend runtime and route wiring · `backend/server.js`
- [API routes](https://github.com/digvijaynarayanpandey/expense-tracker-app/tree/main/backend/routes): rest routes · Auth, dashboard, income and expense route modules · `backend/routes`
- [Auth flow](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/controllers/authController.js): controller · Registration, login and profile update logic · `backend/controllers/authController.js`
- [Dashboard agg](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/controllers/dashboardController.js): controller · Cross-collection summaries and trend calculations · `backend/controllers/dashboardController.js`
- [Income CRUD](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/controllers/incomeController.js): controller · Income create, read, delete and export logic · `backend/controllers/incomeController.js`
- [Expense CRUD](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/controllers/expenseController.js): controller · Expense create, read, delete and export logic · `backend/controllers/expenseController.js`
- [Auth guard](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/middleware/authMiddleware.js): middleware · JWT verification and request user attachment · `backend/middleware/authMiddleware.js`
- [Upload middleware](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/middleware/uploadMiddle.js): multipart middleware · Profile photo upload handling · `backend/middleware/uploadMiddle.js`
- [MongoDB](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/config/db.js): database connection · Mongoose connection setup · `backend/config/db.js`
- [User model](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/models/User.js): mongoose model · Credentials and profile fields · `backend/models/User.js`
- [Income model](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/models/Income.js): mongoose model · User-scoped income transactions · `backend/models/Income.js`
- [Expense model](https://github.com/digvijaynarayanpandey/expense-tracker-app/blob/main/backend/models/Expense.js): mongoose model · User-scoped expense transactions · `backend/models/Expense.js`

## Connections

- App shell → Route pages: renders · Bootstraps route-level screens
- App shell → Layouts: wraps · Uses shared application shells
- Route pages → UI blocks: composes · Pages reuse shared UI blocks
- Layouts → User state: reads · Layouts depend on session-aware user state
- User state → API client: calls · User state uses API client for auth and profile data
- UI blocks → API client: calls · Forms and lists fetch or mutate data via axios
- Image upload → API client: uses · Upload helper sends requests through API layer
- User state → Theme state: separates · Theme preference is independent from auth state
- API client → API server: HTTP · Frontend talks to backend over REST
- API server → API routes: mounts · Express server registers resource routes
- API routes → Auth flow: dispatches · Auth endpoints
- API routes → Dashboard agg: dispatches · Dashboard endpoints
- API routes → Income CRUD: dispatches · Income endpoints
- API routes → Expense CRUD: dispatches · Expense endpoints
- Auth flow → Auth guard: protected by · Protected routes verify JWT bearer tokens
- Dashboard agg → Auth guard: protected by · Dashboard data requires authenticated user
- Income CRUD → Auth guard: protected by · Income CRUD is user-scoped
- Expense CRUD → Auth guard: protected by · Expense CRUD is user-scoped
- Auth flow → Upload middleware: uses · Profile image updates use multipart upload flow
- Auth flow → User model: persists · Auth logic reads and updates user records
- Dashboard agg → Income model: reads · Aggregates income records
- Dashboard agg → Expense model: reads · Aggregates expense records
- Income CRUD → Income model: persists · Income controller reads and writes income records
- Expense CRUD → Expense model: persists · Expense controller reads and writes expense records
- User model → MongoDB: stored in · User data is persisted in MongoDB via Mongoose
- Income model → MongoDB: stored in · Income data is persisted in MongoDB via Mongoose
- Expense model → MongoDB: stored in · Expense data is persisted in MongoDB via Mongoose
- UI blocks → Dashboard agg: shows · Dashboard charts render aggregated summaries
- UI blocks → Income CRUD: manages · Income screens drive create/delete workflows
- UI blocks → Expense CRUD: manages · Expense screens drive create/delete workflows