Budgetter - Your Daily Expenses Tracker

Budgetter is designed to help students and individuals track their daily expenses, analyze their spending habits, and manage their pocket money efficiently. This project was born out of the need for a better system to keep track of personal finances, beyond just noting down expenses without proper analytics.

Table of Contents

1. Features
2. Screenshot of Project
3. Project Structure
4. Technology Stack
5. How to Use Locally
6. Docker (Production)
7. Testing & Quality Gates
8. Contributing
9. API Endpoints
10. Environment Variables
11. Live Demo

Features

User Features

1. Dashboard

• Visualize your total pocket money, expenses, recent spending, and which categories consume the most money.
• Get a quick overview of your financial status at a glance.

2. Profile Management

• Users can view and update personal details including name, email, date of birth, profession, and profile picture.
• Social media links (Instagram, Facebook) can be added to your profile.
• Secure password management with update functionality.

3. Add Expense

• Users can add expenses with the following details: date, name, category, and amount.
• If you've already added an expense today, it will automatically show below in a table displaying today's added expenses.

4. Show Expenses

• By default, this section shows today's expenses.
• It includes a date filter to view expenses based on specific days, displaying details such as ID, name, price, category, and the time the expense was added.

5. Reports & Analytics

• The Reports section provides detailed insights into your spending:
  • Displays all expenses for the current month by default.
  • Includes filters such as:
    • Last 7 days' expenses.
    • Total expenses by category.
    • Date range input for expenses.
    • Select a specific month to view its expenses.

6. Add Money (Wallet Management)

• Users can add the money they receive from any source (e.g., parents, salary) to their account.
• The wallet shows previous money entries with source and date, stored securely in the database.

7. Add Lent Money

• Record money you lend with details (amount, recipient, date). The amount is deducted from your wallet and added back when you mark it as "Money Received".
• Track outstanding loans and money you've lent to others.

8. Delete Account

• Users can permanently delete their account.
• Removes all data, including expenses, lent money, and records. Data is archived in deleted users collection for audit purposes.

9. Authentication & Security

• Email Verification: New users receive a verification link after account creation.
• Forgot Password: Reset password through email with a secure reset link.
• Change Password: Update your password securely through the profile settings.
• Session Management: Active session tracking with token management.
• Google OAuth: Sign in with Google for faster authentication.
• Local Authentication: Traditional email/password login system.

Admin Features

10. User Management

• Admin dashboard to view all registered users.
• User details cards showing comprehensive information.
• Monitor user activity and account status.

11. Newsletter Management

• Upload and manage newsletter content.
• Send updates and announcements to all users.

Additional Features

12. Responsive Design

• Fully responsive UI that works seamlessly on desktop, tablet, and mobile devices.
• Adaptive layout with mobile-optimized navigation.

13. Dark/Light Theme

• Toggle between dark and light mode for comfortable viewing.
• Theme preference is persisted across sessions.

14. Error Tracking & Monitoring

• Integrated with Sentry for real-time error tracking and performance monitoring.
• Improved reliability through proactive issue detection.

15. Animated UI

• Smooth animations and transitions for enhanced user experience.
• Interactive cursor effects on desktop.

---

Screenshot of Project

1. Landing Page

2. Dashboard

---

Project Structure

Budgetter-Webapp/
├── client/                          # Frontend (Vite + React + TypeScript)
│   ├── src/
│   │   ├── components/             # Reusable UI components
│   │   │   ├── admin/              # Admin-specific components
│   │   │   ├── animation/          # Animation components
│   │   │   ├── auth/               # Authentication components
│   │   │   ├── cards/              # Card components
│   │   │   ├── header/             # Header components
│   │   │   ├── home/               # Landing page components
│   │   │   ├── layout/             # Layout components
│   │   │   ├── navbar/             # Navigation components
│   │   │   ├── profile/            # Profile components
│   │   │   ├── seo/                # SEO components
│   │   │   ├── theme/              # Theme components
│   │   │   ├── ui/                 # Base UI components
│   │   │   └── user/               # User-specific components
│   │   ├── features/               # Redux state slices
│   │   │   ├── expenses/           # Expenses state management
│   │   │   ├── sideNavbar/         # Sidebar navigation state
│   │   │   ├── theme/              # Theme state management
│   │   │   ├── user/               # User state management
│   │   │   └── windowWidth/        # Window width state
│   │   ├── hooks/                  # Custom React hooks
│   │   ├── lib/                    # Library configurations
│   │   ├── pages/                  # Route page components
│   │   │   ├── admin/              # Admin pages
│   │   │   ├── auth/               # Authentication pages
│   │   │   ├── home/               # Landing page
│   │   │   └── user/               # User pages
│   │   ├── routes/                 # React Router configuration
│   │   ├── schemas/                # Zod validation schemas
│   │   ├── services/               # API client services
│   │   ├── styles/                 # Global styles
│   │   ├── types/                  # TypeScript type definitions
│   │   └── utils/                  # Utility functions
│   └── public/                     # Static assets
│
├── server/                          # Backend (Express.js + MongoDB)
│   ├── src/
│   │   ├── controllers/            # Route controllers
│   │   ├── db/                     # Database configuration
│   │   ├── middleware/             # Express middleware
│   │   ├── models/                 # Mongoose models
│   │   ├── routes/                 # API routes
│   │   ├── services/               # Business logic services
│   │   └── utils/                  # Utility functions
│   └── public/                     # Email templates & uploads
│
├── .husky/                          # Git hooks configuration
├── .github/                         # GitHub configuration
├── AGENTS.md                        # AI agent instructions
└── CONTRIBUTING.md                  # Contribution guidelines

---

Technology Stack

Frontend

Backend

Services & Integrations

---

How to Use Locally

If you don't want to run server code then neglect server commands

Prerequisites

• Node.js (v16 or higher)
• npm or yarn package manager
• MongoDB (local or MongoDB Atlas)
• Git

Setup Instructions

1. Clone the repository:

   git clone https://github.com/LokeshwarPrasad3/Budgetter-Webapp.git
   cd Budgetter-Webapp

2. Install dependencies for both frontend and backend:

   cd client
   npm install
   
   cd ../server
   npm install

3. Create a .env file in the server folder with the following content:

   PORT=5000
   
   MONGO_URL=mongodb://127.0.0.1:27017/budgetter
   
   ACCESS_TOKEN_SECRET_KEY=<your-access-token-secret>
   ACCESS_TOKEN_SECRET_EXPIRY=3d
   
   RESET_PASSWORD_TOKEN_SECRET=<your-reset-password-token-secret>
   RESET_PASSWORD_TOKEN_SECRET_EXPIRY=1d
   
   ACCOUNT_VERIFICATION_TOKEN_SECRET=<your-verification-token-secret>
   ACCOUNT_VERIFICATION_TOKEN_SECRET_EXPIRY=1d
   
   CLOUDINARY_CLOUD_NAME=<your-cloudinary-cloud-name>
   CLOUDINARY_API_KEY=<your-cloudinary-api-key>
   CLOUDINARY_API_SECRET=<your-cloudinary-api-secret>
   
   ADMIN_GMAIL=<your-admin-gmail>
   GMAIL_PASSKEY=<your-gmail-app-password>
   
   FRONTEND_URL=http://localhost:5173
   SERVER_URL=http://localhost:5000
   

4. Create a .env file in the client folder (optional):

   VITE_SENTRY_DSN=<your-sentry-dsn>
   VITE_API_URL=http://localhost:5000
   

5. Run the backend server:

   cd server
   npm run dev

   The server will start on http://localhost:5000

6. Run the frontend development server:

   cd client
   npm run dev

   The frontend will start on http://localhost:5173

7. Open http://localhost:5173 in your browser to access the application.

---

Docker (Production)

A production-ready Docker setup is provided for the full stack. Local development is unchanged — keep using npm run dev in client/ and server/. Docker is for production builds and (optionally) running a local MongoDB.

Architecture

┌──────────┐  :80      :5000      :27017
│  client  │ ──────▶ │ server │ ──────▶ │ mongo │
│  nginx   │ /api/*  │ node   │ MONGO_URL │       │
└──────────┘          └────────┘           └───────┘
   exposed             internal              internal
   :8080 → :80         (no host port)        (no host port)

• client — multi-stage build: Vite produces static assets, then nginx:alpine serves them. /api/* is reverse-proxied to the backend over the internal docker network.
• server — node:22-alpine, production dependencies only, runs as the non-root node user under tini for proper signal handling.
• mongo — mongo:7 with a persistent named volume (mongo_data).
• All three live on the budgetter-net bridge network. Inter-container traffic uses service names (no hardcoded localhost).

First-time setup

# 1. Copy env templates and fill in real values
cp .env.example .env                  # compose-level vars (mongo creds, VITE_* build args)
cp server/.env.example server/.env    # server runtime secrets (JWT, SMTP, OAuth)
# client/.env is only needed for local `npm run dev`; the docker build reads from root .env

# 2. Build and start the whole stack in the background
docker compose up -d --build

# 3. Open the app
open http://localhost:8080

Common commands

docker compose up -d --build            # build images + start everything
docker compose ps                       # show container status + healthchecks
docker compose logs -f server           # tail backend logs
docker compose logs -f client           # tail nginx access/error logs
docker compose exec server sh           # shell into the backend
docker compose exec mongo mongosh       # mongo shell
docker compose restart server           # restart one service
docker compose down                     # stop stack (mongo data preserved)
docker compose down -v                  # stop AND wipe mongo volume
docker compose build --no-cache client  # force a clean rebuild

docker compose up flow

1. mongo starts and runs its healthcheck (db.adminCommand('ping')) until ready.
2. server starts only after mongo reports healthy (depends_on.condition: service_healthy), connects via MONGO_URL, then exposes /healthz for its own healthcheck.
3. client starts after the server is healthy. nginx serves the SPA on container port 80 and proxies /api/* to server:5000.
4. The host publishes only the client port (default 8080), so the API and database are not directly reachable from outside the docker network.

Production notes

• TLS termination — this stack publishes plain HTTP on port 8080. In a real deploy, put a TLS-terminating proxy (Caddy, Traefik, Nginx, an ALB, Cloudflare) in front of the client container.
• Secrets — never bake secrets into images. server/.env is mounted at runtime via env_file. For real deployments, prefer a secret manager (Docker secrets, SOPS, Vault, cloud KMS).
• Vite vars are build-time — VITE_* values are inlined into the JS bundle when the client image is built. Changing them requires docker compose build client (a runtime restart won't pick them up).
• Image sizes — multi-stage + --omit=dev + alpine bases keep final images small (client ≈ 25 MB on nginx:alpine, server ≈ 180 MB on node:22-alpine).
• Healthchecks — every service has one; orchestrators (compose, swarm, k8s) use them to gate dependents and to auto-restart unhealthy containers.
• No host-exposed API/DB ports — only the client publishes :8080. To debug the API or connect MongoDB Compass from the host, uncomment the ports: blocks in docker-compose.yml.
• Scaling — server is stateless; you can run docker compose up -d --scale server=3 behind a load balancer. The client (nginx) sees them via docker DNS round-robin.
• Restart policy — every service uses restart: unless-stopped so containers come back after host reboots but respect manual docker compose down.

---

Testing & Quality Gates

Frontend

To test the application, use the following credentials:

Username: lokeshwardewangan
Password: 12345

Available Scripts

Frontend (client/)

Command	Description
npm run dev	Starts the Vite development server
npm run build	Runs TypeScript checks and creates production build
npm run lint	Runs ESLint for .ts and .tsx files
npm run typecheck	Runs TypeScript compiler without emitting files
npm run format	Formats files with Prettier

Backend (server/)

Command	Description
npm run dev	Starts the server in development mode
npm run start	Runs the server with Node.js
npm run format	Formats files with Prettier

Pre-commit Hooks

The project uses Husky git hooks to ensure code quality. Before each commit:

• Frontend build and linting are automatically run
• Both frontend and backend files are formatted
• Any formatting changes are automatically staged

Contributing

Contributions are welcome! Please follow these guidelines:

Reporting Issues

Create an issue for any:

• Bug reports
• Feature requests
• Documentation improvements
• Performance issues

Making Contributions

1. Fork the repository
2. Create a feature or fix branch (see branch naming below)
3. Make your changes
4. Run linting and type checks (npm run lint and npm run typecheck in client/)
5. Format your code (npm run format in both client/ and server/)
6. Submit a pull request

Branch Naming Conventions

• feature/feature-name - For new features (e.g., feature/add-budget-export)
• fix/bug-name - For bug fixes (e.g., fix/expense-date-validation)
• chore/task-name - For maintenance tasks (e.g., chore/update-dependencies)

Pull Request Guidelines

• Include a short description of changes
• Link related issue when applicable
• Add screenshots for visible frontend updates
• Ensure all quality gates pass (lint, typecheck, build)
• Follow existing code style and conventions

For detailed contribution guidelines, see CONTRIBUTING.md.

---

API Endpoints

Authentication

Method	Endpoint	Description
POST	/api/users/register	Register a new user
POST	/api/users/login	Login with credentials
POST	/api/users/google-login	Login with Google OAuth
POST	/api/users/forgot-password	Request password reset email
POST	/api/users/reset-password	Reset password with token
POST	/api/users/verify-account	Verify account with token
POST	/api/users/logout	Logout current session
GET	/api/users/profile	Get user profile
PUT	/api/users/profile	Update user profile
DELETE	/api/users/account	Delete user account

Expenses

Method	Endpoint	Description
POST	/api/expenses	Create a new expense
GET	/api/expenses	Get all user expenses
GET	/api/expenses/today	Get today's expenses
PUT	/api/expenses/:id	Update an expense
DELETE	/api/expenses/:id	Delete an expense

Reports

Method	Endpoint	Description
GET	/api/reports/monthly	Get monthly expense report
GET	/api/reports/category	Get expenses by category
GET	/api/reports/date-range	Get expenses for date range

Money Management

Method	Endpoint	Description
POST	/api/users/add-money	Add money to wallet
POST	/api/users/add-lent-money	Record lent money
PUT	/api/users/receive-lent-money	Mark lent money as received

Admin (Protected)

Method	Endpoint	Description
GET	/api/users/admin/all	Get all users (admin only)
POST	/api/users/admin/newsletter	Send newsletter to users

---

Environment Variables

Server (server/.env)

Variable	Description	Required
PORT	Server port (default: 5000)	Yes
MONGO_URL	MongoDB connection string	Yes
ACCESS_TOKEN_SECRET_KEY	Secret for JWT access tokens	Yes
ACCESS_TOKEN_SECRET_EXPIRY	Access token expiration (e.g., 3d)	Yes
RESET_PASSWORD_TOKEN_SECRET	Secret for password reset tokens	Yes
RESET_PASSWORD_TOKEN_SECRET_EXPIRY	Reset token expiration (e.g., 1d)	Yes
ACCOUNT_VERIFICATION_TOKEN_SECRET	Secret for account verification tokens	Yes
ACCOUNT_VERIFICATION_TOKEN_SECRET_EXPIRY	Verification token expiration	Yes
CLOUDINARY_CLOUD_NAME	Cloudinary cloud name	Yes
CLOUDINARY_API_KEY	Cloudinary API key	Yes
CLOUDINARY_API_SECRET	Cloudinary API secret	Yes
ADMIN_GMAIL	Admin email for notifications	Yes
GMAIL_PASSKEY	Gmail app password for email service	Yes
FRONTEND_URL	Frontend URL (for CORS)	Yes
SERVER_URL	Backend API URL	Yes

Client (client/.env)

Variable	Description	Required
VITE_SENTRY_DSN	Sentry DSN for error tracking	No
VITE_API_URL	Backend API URL	No

---

Live Demo

https://budgetter.lokeshwardewangan.in/

Maintainer

Lokeshwar Dewangan

• Role: Full Stack Developer
• Email: lokeshwar.prasad.cse@gmail.com

---

For any questions, feedback, or contributions, feel free to reach out!