A modern personal finance and expense tracking platform built with Spring Boot 3, PostgreSQL, Redis, and WebSocket for real-time budget alerts.
- User Management: Register, login, manage profiles with JWT authentication
- Expense Tracking: Create, update, delete expenses with categories and dates
- Budget Management: Set category-wise budgets for each month with threshold alerts
- Real-time Alerts: WebSocket notifications when budget thresholds are exceeded
- Receipt Upload: Store receipt images locally (10MB max file size)
- Analytics: View spending trends and categorized expense reports
- Multi-currency Support: Track expenses in different currencies
- Spring Boot 3.3.5 with Java 21
- Modular Monolith architecture with clean layering
- PostgreSQL with Flyway migrations for schema management
- Redis for caching and real-time message brokering
- JWT stateless authentication with Spring Security
- WebSocket (STOMP) for real-time budget alerts
- Rate Limiting with Bucket4j to prevent abuse
- Local File Storage for receipts (no cloud dependencies)
- Docker & Docker Compose for local development
- OpenAPI/Swagger documentation
- Testcontainers for integration tests
expense-tracker/
├── src/
│ ├── main/
│ │ ├── java/com/expensetracker/
│ │ │ ├── config/ # Spring configurations
│ │ │ ├── domain/ # Business entities & repositories
│ │ │ │ ├── user/
│ │ │ │ ├── category/
│ │ │ │ ├── expense/
│ │ │ │ ├── budget/
│ │ │ │ ├── alert/
│ │ │ │ └── receipt/
│ │ │ ├── service/ # Business logic
│ │ │ │ ├── auth/
│ │ │ │ ├── user/
│ │ │ │ ├── category/
│ │ │ │ ├── expense/
│ │ │ │ ├── budget/
│ │ │ │ ├── alert/
│ │ │ │ └── storage/
│ │ │ ├── web/ # Controllers, DTOs, filters
│ │ │ │ ├── controller/
│ │ │ │ ├── dto/
│ │ │ │ ├── filter/
│ │ │ │ └── advice/
│ │ │ ├── infrastructure/ # Security, events, persistence
│ │ │ └── shared/ # Exceptions, utilities
│ │ └── resources/
│ │ ├── db/migration/ # Flyway migrations
│ │ ├── application.yml
│ │ └── application-dev.yml
│ └── test/ # Integration and unit tests
├── pom.xml
├── Dockerfile
└── docker-compose.yml
- Java 21+
- Maven 3.8+
- Docker & Docker Compose
-
Clone and build:
mvn clean install
-
Run with Docker Compose (recommended):
docker-compose up --build
App will be available at
http://localhost:8080 -
Manual setup (if not using Docker):
- Start PostgreSQL:
createdb expense_tracker - Start Redis:
redis-server - Run:
mvn spring-boot:run -Dspring-boot.run.arguments="--spring.profiles.active=dev"
- Start PostgreSQL:
POST /api/v1/auth/register # Register new user
POST /api/v1/auth/login # Login
GET /api/v1/categories # Get all user categories
POST /api/v1/categories # Create category
GET /api/v1/categories/{id} # Get category
PUT /api/v1/categories/{id} # Update category
DELETE /api/v1/categories/{id} # Delete category
GET /api/v1/expenses # Get expenses (paginated)
GET /api/v1/expenses/by-date-range # Filter by date range
POST /api/v1/expenses # Create expense
GET /api/v1/expenses/{id} # Get expense
PUT /api/v1/expenses/{id} # Update expense
DELETE /api/v1/expenses/{id} # Delete expense
GET /api/v1/budgets # Get budgets for month
POST /api/v1/budgets # Create budget
GET /api/v1/budgets/{id} # Get budget
GET /api/v1/alerts # Get user alerts (paginated)
GET /api/v1/alerts/unread-count # Get unread alert count
PUT /api/v1/alerts/{id}/read # Mark alert as read
WS /ws/alerts # Connect for real-time budget alerts
Subscribe to: /user/queue/alerts
- Swagger UI:
http://localhost:8080/swagger-ui.html - OpenAPI JSON:
http://localhost:8080/v3/api-docs - Health Check:
http://localhost:8080/actuator/health
DB_HOST=localhost
DB_PORT=5432
DB_NAME=expense_tracker
DB_USERNAME=tracker
DB_PASSWORD=secret
REDIS_HOST=localhost
REDIS_PORT=6379
JWT_SECRET=your-secret-key-minimum-256-bits
SERVER_PORT=8080
UPLOAD_DIR=./uploads- JWT-based authentication (15-min access, 7-day refresh tokens)
- Role-based access control (ADMIN, USER, VIEWER)
- BCrypt password hashing with strength 12
- Stateless session management (SessionCreationPolicy.STATELESS)
- Redis caching for expenses, budgets, user profiles
- Database indexing on frequently queried columns
- Rate limiting (10 req/min for anonymous, 200 req/min for authenticated)
- Lazy loading for JPA relationships
- WebSocket with STOMP protocol for budget alerts
- Transactional event listeners using Spring Application Events
- Async event processing with dedicated thread pool
- Flyway migrations for version-controlled schema
- PostgreSQL for relational data with ACID transactions
- Hibernate JPA with proper fetch strategies and lazy loading
- Audit fields (createdAt, updatedAt, createdBy, updatedBy) on all entities
# Run all tests
mvn test
# Run only integration tests
mvn verify
# Run with coverage
mvn test jacoco:reportTests use Testcontainers for PostgreSQL and Redis, ensuring tests run against real databases.
docker build -t expense-tracker:latest .
docker run -p 8080:8080 expense-tracker:latestdocker-compose up -d
docker-compose logs -f app
docker-compose down- Export expenses to CSV/PDF
- Recurring expenses automation
- Multi-user budget sharing (family accounts)
- Mobile app (React Native)
- Machine learning-based expense categorization
- Integration with banking APIs
- Advanced analytics and forecasting
MIT