ExpensePilot

Personal finance, in flight.
Track every rupee, from takeoff to clarity.

---

📖 Overview

ExpensePilot is a full-stack personal finance application that helps users manage income, expenses, and budgets — and understand their financial health at a glance. It pairs a modern, glassmorphic, dark-mode-only React interface with a secure Node.js/Express + MongoDB backend, giving users a calm, focused space to log transactions, set monthly limits, and explore spending trends through interactive charts.

Built as a full end-to-end product: authentication, protected routes, RESTful APIs, persistent data models, and a polished analytics dashboard — all in one codebase.

✨ Features

• 🔐 Secure Authentication — JWT-based auth with httpOnly cookie sessions and protected route middleware
• 💵 Income Tracking — Add, edit, delete, filter, search, and sort income records
• 💸 Expense Management — Categorized expense entries with dates and descriptions
• 📊 Budget Monitoring — Set a monthly limit, track category-level spending caps, and get visual warning states as you approach your limit
• 📈 Analytics Dashboard — Income vs. expense trends, category distribution, and top spending categories via interactive charts
• 🌙 Modern Dark UI — Glassmorphism, animated gradients, floating blobs, cursor-glow effects, skeleton loaders, and confetti micro-interactions
• 📱 Responsive Design — Fully usable across desktop and mobile viewports
• 🔒 Privacy First — User data is scoped per-account and never shared

🖼️ Screenshots

Sign In	Dashboard
Income	Expenses
Budget	Analytics
Profile

🏗️ Architecture

Frontend

Tech	Purpose
React 19	UI library
Vite	Build tool & dev server
TypeScript	Type safety
TanStack Router	Route-based navigation
TanStack Query	Server state & caching
Tailwind CSS	Utility-first styling
Recharts	Data visualization
Sonner	Toast notifications

Backend

Tech	Purpose
Node.js	Runtime
Express.js	REST API framework
MongoDB + Mongoose	Database & ODM
JWT (httpOnly cookies)	Authentication

🗂️ Project Structure

ExpensePilot/
├── backend/
│   ├── controllers/     # Auth, income, expense, budget, analytics logic
│   ├── models/           # Mongoose schemas (User, Income, Expense, Budget)
│   ├── routes/           # API route registration
│   ├── middleware/       # Auth & error handling
│   └── server.js          # Express app entry point
│
└── frontend/
    ├── src/
    │   ├── routes/        # Page-level routes (dashboard, income, expenses, budget, analytics, auth)
    │   ├── components/    # Shared UI shell, sidebar, layouts, icons
    │   └── lib/
    │       ├── api.ts     # API client
    │       └── store.ts   # Client-side UI/session state
    └── vite.config.ts

🧩 Data Models

Model	Fields
User	account details, hashed password, currency preference
Income	amount, category, description, date, owner
Expense	amount, category, description, date, owner
Budget	one monthly budget per user, category limits

🚀 Getting Started

Prerequisites

• Node.js (v18+ recommended)
• MongoDB (local instance or MongoDB Atlas)
• npm or yarn

Installation

# Clone the repository
git clone https://github.com/wasay-khanzada/ExpensePilot.git
cd ExpensePilot

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

Environment Variables

Create a .env file inside backend/:

PORT=5000
MONGO_URI=your_mongodb_connection_string
JWT_SECRET=your_jwt_secret
NODE_ENV=development

Create a .env file inside frontend/ (if applicable):

VITE_API_BASE_URL=http://localhost:5000/api

Running Locally

# Start the backend (from /backend)
npm run dev

# Start the frontend (from /frontend, in a separate terminal)
npm run dev

The frontend will typically run at http://localhost:5173 and the backend API at http://localhost:5000.

🗺️ Roadmap

• Automated test suite for backend endpoints and critical frontend flows
• Full backend persistence for category budget limits
• Reduce reliance on local client-side store in favor of backend as single source of truth
• CI pipeline for linting, testing, and builds
• Production deployment configuration & documentation

See CHANGELOG.md for release history.

🤝 Contributing

Contributions, issues, and feature requests are welcome! Please read CONTRIBUTING.md before submitting a pull request.

📄 License

This project is licensed under the MIT License.

👤 Author

Wasay Khanzada GitHub: @wasay-khanzada

---

_{Built with ☕ and a lot of dark mode.}