💸 GroupPay

Advanced Expense Splitting & Settlement Engine

Features • Tech Stack • API Docs • Getting Started • Deployment

---

Overview

GroupPay is a high-performance backend system engineered to simplify complex group finances. Think of it as the engine behind a "Pro" version of Splitwise. It handles user authentication, complex expense splitting (Equal, Exact, Percentage), and features a smart settlement algorithm to minimize the number of transactions needed to settle up.

---

Project Status & Roadmap

Current Status: ✅ Core Backend Complete (Deployed)

Phase	Feature	Status
Phase 1	JWT Auth, Groups, Settlements	✅ Completed
Phase 1	Dockerization & Cloud Deployment	✅ Completed
Phase 2	Password Reset Flow	✅ Completed
Phase 3	WebSocket Notifications	🚧 In Progress
Future	Social Login (Google/FB)	📅 Planned
Future	Native Android App Integration	📅 Planned

---

Features

Robust Security JWT Authentication: Stateless & Scalable. Password Reset Flow: Secure email-token verify loop. OAuth2 Ready: Modular design for Social Logins.	Smart Financials Dynamic Splitting: Handles Equal, Exact amounts, and Percentages. Algorithm: Graph-based debt simplification. Precision: BigDecimal for financial accuracy.
Group Dynamics Deep linking for group invites. Cascading deletion for clean data management. Role-based access control (Admin/User).	Modern Tech Dockerized: "Run anywhere" container. Swagger UI: Interactive API playground. Cloud Native: TiDB & Render optimized.

---

Tech Stack

Component	Technology	Description
Language	Java 21	Latest LTS version for performance.
Framework	Spring Boot 3.4	Core framework for DI & Web MVC.
Database	MySQL 8 / TiDB	Relational persistence. Cluster-ready.
Security	Spring Security 6	JWT + BCrypt + CSRF protection.
Docs	SpringDoc OpenAPI	Automated Swagger UI generation.
Ops	Docker	Multi-stage build for optimized image size.

---

The Algorithm: Minimum Cash Flow

GroupPay isn't just a CRUD app; it solves the NP-hard problem of debt simplification efficiently using a Greedy Minimum Cash Flow Algorithm.

The Problem

Imagine 3 friends: Ram, Sham, and Krishna.

1. Ram pays ₹50 for Sham.
2. Sham pays ₹50 for Krishna.

Naive Approach (2 Transactions):

• Sham gives Ram ₹50.
• Krishna gives Sham ₹50.
• Sham is just a middleman moving money!

The Solution (1 Transaction)

Our algorithm calculates the Net Balance for each person:

• Ram: +₹50 (He is owed)
• Sham: 0 (Owes 50, Owed 50 -> Net 0)
• Krishna: -₹50 (He owes)

Optimized Result:

• Krishna pays Ram ₹50 directly.
• Sham does nothing.

Why this is better?

Drastically reduces bank transfers in large groups.

• Input: N people with M transactions.
• Output: At most N-1 transactions to settle EVERYONE.

---

📚 API Documentation

Explore the API interactively. No external tools needed.

Environment	URL	Status
Live Demo	**Launch Swagger UI **	🟢 Online
Localhost	View Local Docs	🟡 When running

🔑 Key Endpoints

Method	Endpoint	Description	Auth?
POST	/auth/register	Register a new user	❌
POST	/auth/login	Login & receive JWT	❌
POST	/auth/forgot-password	Request password reset token	❌
GET	/groups	List all groups for user	✅
POST	/groups	Create a new group	✅
POST	/expenses	Add a split expense	✅
GET	/settlements/group/{id}	Calculate settlement graph	✅

📝 Example Request (cURL)

Register a User:

curl -X POST "https://your-app-url.onrender.com/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "mahir_dev",
    "email": "mahir@example.com",
    "password": "securePassword123"
  }'

---

✅ Prerequisites

Ensure you have the following installed before running locally:

• Java 21 (JDK)
• MySQL 8.0 (or compatible)
• Maven 3.9+
• Docker & Docker Compose (Optional, for containerization)

Getting Started

Option 1: Run with Docker (Recommended)

# 1. Build the image
docker build -t grouppay-backend .

# 2. Run container (With env vars)
docker run -p 8081:8081 \
  -e SPRING_DATASOURCE_URL="jdbc:mysql://host:port/db" \
  -e SPRING_DATASOURCE_USERNAME="root" \
  -e SPRING_DATASOURCE_PASSWORD="password" \
  grouppay-backend

Option 2: Run from Source

1. Clone & Configure: Update src/main/resources/application.yml with your DB creds.
2. Run:

   ./mvnw spring-boot:run

3. Access: Server starts at http://localhost:8081

---

Architecture

The project is built as a Modular Monolith, ensuring strict boundaries exist between features (User, Group, Expense) while keeping the deployment simple.

System Design

graph TD
    Client[Mobile/Web Client] -->|REST API| LoadBalancer
    LoadBalancer -->|HTTPS| SpringBoot[Spring Boot Backend]
    SpringBoot -->|Read/Write| DB[(TiDB / MySQL)]
    
    subgraph "Modular Monolith"
        Auth[User Module]
        Grp[Group Module]
        Exp[Expense Module]
        Set[Settlement Engine]
    end
    
    SpringBoot --> Auth
    SpringBoot --> Grp
    SpringBoot --> Exp
    Exp --> Set

Loading

📂 Project Structure

The project follows a Domain-Driven Design (DDD) architecture. Each feature (User, Group, Expense) is a self-contained module with its own API, Service, and Repository layers.

com.grouppay
├──  user
│   ├── api            # AuthController (Login, Register, ForgotPwd)
│   ├── application    # PasswordResetService, LoginUserService
│   └── domain         # User Entity, PasswordResetToken
├──  group
│   ├── api            # GroupController
│   └── application    # GroupService, MemberService
├──  expense
│   ├── api            # ExpenseController
│   └── domain         # Expense, ExpenseSplit (Polymorphic inputs)
├──  settlement
│   ├── application
│   │   ├── MinimumCashFlowService.java  #  The Greedy Algorithm
│   │   └── BalanceCalculationService.java
│   └── domain         # Settlement Entity
├──  notification
│   └── event          # ExpenseAddedEvent, MemberAddedEvent
└──  security        # JwtAuthenticationFilter, SecurityConfig

---

_{Engineered and Developed by Mahir Aggarwal}