Personal Finance Tracker

A full-stack web application to track income, expenses, and financial analytics. Built with Node.js, Express, MongoDB, and modern JavaScript.

Features

• User Authentication: Register and login with JWT-based authentication
• Transaction Management: Add, view, and delete income/expense transactions
• Budget Tracking: Set and monitor budgets
• Analytics Dashboard: View spending trends and predictions by month
• Secure API: Protected routes with JWT middleware

Tech Stack

Backend

• Node.js v22+ with ES modules
• Express.js — REST API framework
• MongoDB Atlas — NoSQL database
• JWT — JSON Web Tokens for authentication
• bcryptjs — Password hashing
• dotenv — Environment variable management
• nodemon — Development server with auto-reload

Frontend (placeholder)

• React / Vue / vanilla JS (to be implemented)

Project Structure

personal-finance-tracker/
├── server/
│   ├── controllers/
│   │   ├── authController.js       # Auth logic (register, login)
│   │   ├── transactionController.js # Transaction CRUD
│   │   ├── budgetController.js      # Budget management
│   │   └── analyticsController.js   # Analytics & predictions
│   ├── routes/
│   │   ├── authRoutes.js
│   │   ├── transactionRoutes.js
│   │   ├── budgetRoutes.js
│   │   └── analyticsRoutes.js
│   ├── models/
│   │   ├── userModel.js
│   │   ├── transactionModel.js
│   │   └── budgetModel.js
│   ├── middleware/
│   │   └── authMiddleware.js       # JWT protection
│   ├── .env                        # Environment variables (not tracked)
│   ├── .gitignore
│   ├── server.js                   # Express app setup
│   └── package.json
└── README.md

Installation

Prerequisites

• Node.js v22+
• MongoDB Atlas account
• npm or yarn

Setup

1. Clone the repository:

git clone https://github.com/devdammie/personal-finance-tracker.git
cd personal-finance-tracker

2. Install dependencies:

cd server
npm install

3. Create a .env file in server/ with your credentials:

MONGO_URI=your-mongo_uri
PORT=6000
NODE_ENV=development
JWT_SECRET=your-secret-key-here

4. Start the development server:

npm run dev

Server runs on http://localhost:6000

API Endpoints

Authentication

• POST /api/auth/register — Register a new user
• POST /api/auth/login — Login and receive JWT token

Transactions (Protected)

• GET /api/transactions — Get all user transactions
• POST /api/transactions — Create a new transaction
• DELETE /api/transactions/:id — Delete a transaction

Budget (Protected)

• GET /api/budget — Get budgets
• POST /api/budget — Create a budget

Analytics (Protected)

• GET /api/analytics — Get spending trends and predictions

Environment Variables

MONGO_URI         # MongoDB connection string
PORT              # Server port (default: 6000)
NODE_ENV          # development or production
JWT_SECRET        # Secret key for JWT signing

Usage Example

Register a user

curl -X POST http://localhost:6000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"securepass"}'

Login

curl -X POST http://localhost:6000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"securepass"}'

Response includes JWT token:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Add a transaction (authenticated)

curl -X POST http://localhost:6000/api/transactions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"expense","amount":50,"category":"food","date":"2025-12-04"}'

Security Notes

• Never commit .env files — add to .gitignore
• Rotate secrets if accidentally exposed (MongoDB password, JWT_SECRET, etc.)
• Use environment variables for all sensitive data
• JWT tokens expire after 7 days (configurable)
• Passwords are hashed with bcryptjs before storage

Development Scripts

npm run dev       # Start with nodemon (auto-reload)
npm start         # Start production server
npm test          # Run tests (when implemented)

Future Enhancements

• Frontend UI (React/Vue)
• Unit and integration tests
• Category-based budget limits
• Export transactions to CSV
• Email notifications for budget overruns
• Multi-currency support
• Dashboard with charts

Troubleshooting

MongoDB connection error

• Check IP is whitelisted in MongoDB Atlas Network Access
• Verify MONGO_URI in .env is correct
• Ensure cluster is not paused

JWT authentication fails

• Confirm JWT_SECRET env var is set
• Check token hasn't expired
• Verify Authorization header format: Bearer <token>

Module not found errors

• Ensure all imports include .js extension (ESM)
• Verify package.json has "type": "module"
• Check file paths match actual filenames

License

MIT License — feel free to use this project for learning or personal use.

Contact

For questions or issues, please open a GitHub issue or contact devdammie