https://github.com/muuhesham/finance-tracker
Finance Tracker Web Application with MERN Stack
https://github.com/muuhesham/finance-tracker
expressjs mongodb nodejs react vibe-coding
Last synced: 13 days ago
JSON representation
Finance Tracker Web Application with MERN Stack
- Host: GitHub
- URL: https://github.com/muuhesham/finance-tracker
- Owner: muuhesham
- Created: 2026-05-07T08:06:28.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-07T08:22:08.000Z (about 1 month ago)
- Last Synced: 2026-05-07T10:28:36.375Z (about 1 month ago)
- Topics: expressjs, mongodb, nodejs, react, vibe-coding
- Language: JavaScript
- Homepage:
- Size: 71.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# FinanceFlow Personal Finance Management System
FinanceFlow is a production-ready personal finance management system built with `Node.js + Express.js`, `React`, and `MongoDB`. It helps users track income and expenses, monitor monthly behavior through charts, and receive automated end-of-month financial tips generated by a rule-based insights engine.
## Highlights
- JWT-based registration and login
- Expense and income CRUD with categories, notes, and timestamps
- Dashboard with monthly summary, category chart, trend chart, and recent transactions
- Rule-based monthly insights powered by Strategy Pattern
- Clean architecture with Repository, Strategy, and Factory patterns
- Unit-tested backend services
- Full documentation set including SRS, UML, architecture notes, Agile sprint simulation, API guide, and implementation explanation
## Stack
- Backend: `Node.js`, `Express.js`, `Mongoose`
- Frontend: `React`, `Vite`, `Recharts`, `Framer Motion`
- Database: `MongoDB`
- Testing: `Vitest`
# Project Setup & Running Instructions
## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Project Structure](#project-structure)
3. [Backend Setup](#backend-setup)
4. [Frontend Setup](#frontend-setup)
5. [Running the Application](#running-the-application)
6. [Testing](#testing)
7. [Building for Production](#building-for-production)
8. [Troubleshooting](#troubleshooting)
---
## Prerequisites
Before starting, ensure you have the following installed on your system:
### Required Software
- **Node.js** (v16 or higher) - [Download](https://nodejs.org/)
- **npm** (comes with Node.js)
- **MongoDB** (running locally) - [Download](https://www.mongodb.com/try/download/community)
- **MongoDB Compass** (optional, for database GUI) - [Download](https://www.mongodb.com/products/compass)
- **Git** - [Download](https://git-scm.com/)
### Verify Installation
```powershell
node --version
npm --version
mongod --version
## Project Structure
```text
finance-flow-system/
├─ backend/ # Express API, controllers, routes, services, models, validators
├─ frontend/ # React dashboard and auth UI
├─ docs/ # SRS, UML, architecture, Agile, API, tests, explanation
├─ package.json
```
## Prerequisites
- MongoDB running locally and accessible from MongoDB Compass on `mongodb://127.0.0.1:27017`
- MongoDB Compass installed for local database inspection and connection testing
- Node.js and npm installed
## Environment Setup
### API
Copy `backend/.env.example` to `backend/.env` and set:
```env
PORT=8000
MONGODB_URI=mongodb://127.0.0.1:27017/finance-flow
JWT_SECRET=hsgA+uKMxv6T1EhbJAjSwDX+mzTap63gGqVwaiFbayg=
CLIENT_URL=http://localhost:5173
```
### Web
Copy `frontend/.env.example` to `frontend/.env`:
```env
VITE_API_URL=http://localhost:8000/api
```
## Install
From the repository root, install dependencies for the backend and frontend apps:
```powershell
cd backend && npm install
cd ..\frontend && npm install
```
## MongoDB Compass Setup
1. Start your local MongoDB server.
2. Open MongoDB Compass.
3. Connect using `mongodb://127.0.0.1:27017`.
4. Create or use the `finance-flow` database.
5. Keep the API env value aligned with that connection:
```env
MONGODB_URI=mongodb://127.0.0.1:27017/finance-flow
```
## Run the Backend
From the project root, start the API:
```powershell
npm run dev:api
```
The backend will run at [http://localhost:8000](http://localhost:8000).
## Run the Frontend
In a second terminal from the project root:
```powershell
npm run dev:web
```
The frontend will run at [http://localhost:5173](http://localhost:5173).
## Run Both Together
If you want to run both apps manually, start each in a separate terminal:
```powershell
npm run dev:api
npm run dev:web
```
## Test and Build
```powershell
npm run test:api
npm run build:web
```
## Documentation Index
- SRS: [docs/SRS.md](docs/SRS.md)
- Architecture: [docs/architecture.md](docs/architecture.md)
- API reference: [docs/api.md](docs/api.md)
- Test cases: [docs/test-cases.md](docs/test-cases.md)
- Git workflow: [docs/version-control.md](docs/version-control.md)
- Agile simulation: [docs/agile/scrum-plan.md](docs/agile/scrum-plan.md)
- Detailed implementation explanation: [docs/explanation.md](docs/explanation.md)
- UML diagrams:
- [docs/uml/use-case.md](docs/uml/use-case.md)
- [docs/uml/class-diagram.md](docs/uml/class-diagram.md)
- [docs/uml/sequence-diagram.md](docs/uml/sequence-diagram.md)
- [docs/uml/activity-diagram.md](docs/uml/activity-diagram.md)
## Delivered Features
- Authentication with secure password hashing and JWT sessions
- Transaction management with add, edit, and delete
- Monthly dashboard with category and trend visualization
- End-of-month smart tips generated from spending rules
- Responsive desktop-first interface with subtle motion and clean visual hierarchy
## Notes
- Insights are cached per user and month after generation.
- MongoDB is used through a local connection that you can verify in MongoDB Compass.
- The project uses npm for package management and local app startup.