Expense Tracker

A production-ready Expense Tracker backend built using Spring Boot, designed to manage user expenses securely while providing analytics, insights, and advanced backend features such as authentication, file uploads, caching, rate limiting, and email notifications.

This project is developed as part of the Backend Engineering with Spring Boot – Final Term Project and fully complies with all mandatory and advanced requirements.

---

🚀 Project Overview

Expense Tracker is a RESTful backend application that allows users to register and authenticate securely using JWT, manage expenses and categories, upload and download expense receipts, view analytics and spending insights, receive email notifications for reports and alerts, and access APIs protected with rate limiting and caching.

The system follows industry-standard backend architecture and best practices.

---

Project Compliance

• Backend Framework: Spring Boot
• Architecture: Layered (Controller → Service → Repository)
• Database: PostgreSQL
• Authentication: JWT
• Documentation: Swagger / OpenAPI

✔ Designed to simulate real-world production backend systems

---

🧱 Architecture and Features

The project follows a strict layered architecture where each package has a clear responsibility:

• controller/ – REST API endpoints handling incoming HTTP requests and responses.
• service/ – Business logic, orchestration, and application rules.
• repository/ – Database access using Spring Data JPA.
• model/ – Entity definitions mapped to database tables.
• dto/ – Request and response objects for cleaner API contracts.
• config/ – Security, JWT, Swagger, cache, and other framework configurations.
• exception/ – Global exception handling and custom error responses.
• util/ – Utility and helper classes.

All features are implemented on top of this architecture:

• Authentication & Security: User registration and login, JWT-based authentication, role-based access control, BCrypt password hashing, and secure API access using Spring Security.
• Expense Management: Create, update, delete, and fetch expenses; support for fetching by ID, listing with pagination and filtering, and soft delete for better data integrity.
• Category Management: Create and manage categories, assign default categories for users, and track expenses category-wise.
• Analytics & Insights: Monthly expense summary, category-wise breakdown, daily spending trends, highest expense detection, and intelligent spending insights.
• File Upload: Upload and download expense receipts (PDF, PNG, JPEG) with organized storage per user and per expense.
• Email Integration: Monthly expense report emails, budget threshold alerts, and SMTP-based email sending.
• Performance & Reliability: Caching using Caffeine, API rate limiting using Bucket4j, optimized database queries with indexes, and idempotency support to prevent duplicate requests.

---

🛠 Tech Stack

Component	Technology
Language	Java 21
Backend	Spring Boot
Security	Spring Security, JWT
Database	PostgreSQL
ORM	Spring Data JPA
Caching	Caffeine
Rate Limiting	Bucket4j
Documentation	Swagger / OpenAPI
Build Tool	Maven
Containerization	Docker

---

⚙️ Setup Instructions

Prerequisites

• Java 21
• Maven 3.9+
• PostgreSQL 15+
• Docker (optional)

1️⃣ Database Setup

First, create the PostgreSQL database:

createdb expense_tracker

Or using Docker:

docker run --name postgres-expense \
  -e POSTGRES_DB=expense_tracker \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 -d postgres:15

2️⃣ Application Configuration

Update your application.properties:

spring.datasource.url=jdbc:postgresql://localhost:5432/expense_tracker
spring.datasource.username=postgres
spring.datasource.password=password

jwt.secret=your-secret-key

For email:

spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username=your-email@gmail.com
spring.mail.password=your-app-password

3️⃣ Build and Run the application:

  ./mvnw clean install
  ./mvnw spring-boot:run

Once started, the application will be available at:

http://localhost:8080

---

🐳 Docker Deployment

Start using Docker Compose:

docker-compose up -d

Services started:

• PostgreSQL

• Expense Tracker Backend

Stop services:

docker-compose down

---

📘 API Documentation

Swagger UI available at:

http://localhost:8080/swagger-ui.html

---

🔗 API Endpoints (Overview)

🔑 Authentication

POST /api/auth/register  
POST /api/auth/login

💸 Expenses

POST /api/expenses  
GET /api/expenses  
GET /api/expenses/{id}  
PUT /api/expenses/{id}  
DELETE /api/expenses/{id}

🗂 Categories

GET /api/categories  
POST /api/categories  
PUT /api/categories/{id}  
DELETE /api/categories/{id}

📊 Analytics

GET /api/analytics/monthly-summary  
GET /api/analytics/category-breakdown  
GET /api/analytics/daily-trend  
GET /api/analytics/insights

🔐 Authentication

All protected APIs require JWT in the header:

Authorization: Bearer <jwt-token>

---

🧪 Testing

Run unit tests:

./mvnw test

🗄️ Database Schema

The Expense Tracker backend uses a normalized PostgreSQL schema to keep user, expense, and category data consistent and easy to query.

• users

  • id (PK)
  • name
  • email (unique)
  • password_hash
  • role (e.g. USER, ADMIN)
  • created_at
  • updated_at

• categories

  • id (PK)
  • user_id (FK → users.id, nullable for global/default categories)
  • name
  • description
  • created_at
  • updated_at

• expenses

  • id (PK)
  • user_id (FK → users.id)
  • category_id (FK → categories.id)
  • amount
  • currency
  • description
  • expense_date
  • is_deleted (soft delete flag)
  • created_at
  • updated_at

• receipts

  • id (PK)
  • expense_id (FK → expenses.id)
  • file_name
  • file_path
  • content_type
  • uploaded_at

• email_notifications

  • id (PK)
  • user_id (FK → users.id)
  • type (e.g. MONTHLY_REPORT, BUDGET_ALERT)
  • status (e.g. PENDING, SENT, FAILED)
  • created_at
  • sent_at

This structure allows efficient analytics such as category-wise totals, monthly summaries, and per-user insights while preserving history via soft deletes.

---