💰 Splitter — Smart Financial Ledger & Debt Simplifier

A robust Spring Boot backend that solves the N-way setoff problem to simplify group expenses.

---

📖 Overview

Splitter is a backend financial system to track shared expenses within groups.
Beyond logging expenses, Splitter includes a Debt Simplification Engine that reduces the total number of transactions required to settle balances.

🔹 Example
If Alice owes Bob ₹100 and Bob owes Charlie ₹100, Splitter auto-resolves this chain to:

➡️ Alice pays Charlie ₹100

Bob is no longer part of the settlement!

🏗️ System Architecture

The project uses a Layered Architecture:

• Controller Layer → Request handling & authentication
• Service Layer → Business logic + Debt simplification algorithm
• Repository Layer → Spring Data JPA with PostgreSQL

---

🗄️ Database Design

Designed with a normalized schema for scalable group expense tracking.
Many-to-Many relationships between Users ↔ Groups are handled through an association entity:
expense_split stores per-user debt responsibilities.

---

💡 Key Engineering Features

🧠 1) Debt Simplification Algorithm

• Exact minimum settlement is an NP-Hard problem (O(2^N))
• Implemented a Greedy Approximation using Min-Max Heaps
• Achieves Practical Complexity: O(N log N)

📌 Strategy:
Match largest debtor with largest creditor until all balances reach zero.

---

🛡️ 2) Security & Best Practices

• JWT-based Stateless Authentication
• Custom DTOs to:
  • Avoid circular references
  • Prevent password exposure
• ModelMapper + Lombok for clean codebase

---

🛠️ Tech Stack

Category	Tools
Language	Java 21
Backend	Spring Boot 3 (REST APIs)
Database	PostgreSQL 16 + JPA (Hibernate)
Security	Spring Security + JWT
Documentation	Swagger / OpenAPI
Build Tools	Maven
Others	Lombok, ModelMapper

---

🚀 Getting Started

Prerequisites

• Java 21
• Maven
• PostgreSQL installed & running

Installation

git clone https://github.com/yourusername/splitter.git
cd splitter

(Optional) Build:

mvn clean package

---

Configure Database

Edit:
src/main/resources/application.properties

spring.datasource.url=jdbc:postgresql://localhost:5432/splitter_db
spring.datasource.username=your_postgres_user
spring.datasource.password=your_postgres_password

spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

For production, keep secrets out of properties files — use environment variables or a secrets manager.

---

Run the Application

mvn spring-boot:run

By default the app runs on http://localhost:8080.

---

🧪 Testing the Simplification Logic

Quick manual test:

1. Create a group.
2. Add 3 users: A, B, C.
3. Add expenses:

# Example (pseudo-requests)
POST /api/groups       -> create group
POST /api/groups/{id}/users -> add users A, B, C
POST /api/expenses     -> A pays 100 (split A,B)
POST /api/expenses     -> B pays 50 (split B,C)

4. GET simplified transactions:

GET /api/groups/{id}/transactions

Expected result: instead of A ⇄ B ⇄ C chains, system suggests minimal set like C pays A directly (depending on net balances).

---

📄 API Docs

Swagger / OpenAPI available at:

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

Use this to explore endpoints, request/response DTOs and authentication flows.

---

👤 Author & Contact

Mayank Jain

• GitHub: https://github.com/mayank1008-tech
• LinkedIn: https://www.linkedin.com/in/mayank-jain-78a6bb321/
• YouTube: https://youtu.be/7v30Eg9OV_c?si=uRAZQTphoYvfvD9z

---

✅ Notes & Improvements

• Add unit & integration tests for the Debt Simplifier.
• Add secure refresh-token flow and token revocation.
• Add CSV export & lightweight frontend visualizer.

---

⭐ Support

If you like this project — star the repo! ⭐
More features coming soon 🚀