DebtLedger – Backend (MVP v1.0.0)

📌 Project Overview

DebtLedger is a backend-first, production-style REST API designed to help users track loans, EMIs (Equated Monthly Installments), and overall debt exposure over time. The system supports user authentication, loan lifecycle management, EMI schedules, and analytical dashboards.

This repository represents the fully completed and tested Backend MVP, built with Spring Boot + PostgreSQL, and is tagged as a stable baseline for frontend development.

---

🎯 Problem Statement (Phase 0 – Idea Normalization)

Most individuals managing multiple loans struggle with:

• Tracking monthly EMIs across loans
• Knowing remaining payable amounts
• Understanding future EMI load
• Getting a consolidated debt overview

DebtLedger solves this by providing:

• Centralized loan tracking
• Deterministic EMI schedules
• Strict state transitions (PAID / MISSED)
• Real-time debt analytics

The goal was to build a clean, extensible backend that mirrors real-world financial rules.

---

🧱 High-Level Architecture

Client (Postman / Frontend)
        │
        ▼
REST Controllers
        │
        ▼
Service Layer (Business Rules)
        │
        ▼
Repository Layer (JPA)
        │
        ▼
PostgreSQL Database

Cross-cutting concerns:

• JWT Authentication
• Global Exception Handling
• Request Validation
• Stateless Security

---

🛠 Tech Stack

• Language: Java 21
• Framework: Spring Boot 3.3.x
• Security: Spring Security + JWT
• Database: PostgreSQL
• ORM: Spring Data JPA (Hibernate)
• Validation: Jakarta Bean Validation
• API Docs: OpenAPI / Swagger
• Build Tool: Maven

---

🔐 Authentication & Security

Supported Authentication Providers

• LOCAL (Email + Password)
• GOOGLE OAuth (token-based)

Security Model

• Stateless JWT authentication
• No server-side sessions
• JWT validated via filter on every request

Public Endpoints

• /auth/signup
• /auth/login
• /auth/oauth/google
• /swagger-ui/**

All other endpoints require a valid JWT.

---

📦 Core Domain Model

User

• id
• name
• email
• passwordHash
• authProvider

Loan

• id
• userId
• name
• emiAmount
• totalTenureMonths
• emiStartDate
• status (ACTIVE / CLOSED)

EMI Schedule Entry

• id
• loanId
• yearMonth
• status (PENDING / PAID / MISSED)

Constraint: (loanId, yearMonth) is unique

---

📘 Loan Lifecycle Rules (LLD Highlights)

• Loan starts in ACTIVE state
• EMI schedule is generated upfront
• Each EMI can transition:
  • PENDING → PAID
  • PENDING → MISSED
• PAID / MISSED is terminal
• CLOSED loans:
  • Cannot be edited
  • Cannot have EMI status updates

All rules are enforced at service level.

---

📑 API Modules

1️⃣ Auth Module

• User signup & login
• JWT generation
• OAuth Google login

2️⃣ Loan Module

• Create loan
• Update loan (controlled regeneration of EMI schedule)
• Close loan
• Fetch single loan details
• Fetch loan summaries (dashboard/table view)

3️⃣ EMI Schedule Module

• Fetch EMI schedule per loan
• Update EMI status (PAID / MISSED)
• Strict ownership and state checks

4️⃣ Dashboard Module

Provides analytical insights:

Debt Overview

• Total active loans
• Total payable amount
• Remaining payable amount

Monthly EMI Load

• EMI count for current month
• Total EMI amount

Yearly EMI Calendar

• Month-by-month EMI distribution for a given year

---

⚠️ Validation & Error Handling

Validation

• Bean-level request validation
• Consistent validation errors

Global Error Response

{
  "timestamp": "...",
  "status": 400,
  "error": "VALIDATION_ERROR",
  "message": "...",
  "path": "/endpoint"
}

Handled errors:

• Validation errors
• Unauthorized / Forbidden
• Resource not found
• Illegal state transitions
• Internal server errors

---

🧪 Testing Strategy

All APIs were tested manually using Postman:

• Authentication flows
• Duplicate & invalid inputs
• Loan creation, update, closure
• EMI state transitions
• Edge cases (closed loans, invalid access)
• Dashboard calculations

Every business rule was validated against real API responses.

---

🗄 Database Notes

• PostgreSQL used as primary datastore
• Hibernate ddl-auto=update
• YearMonth stored as String via AttributeConverter

---

🏷 Versioning & Stability

• Backend MVP tagged as:

  backend-mvp-v1.0.0

Built end-to-end with a strong focus on:

• Clean architecture
• Deterministic business rules
• Production-grade patterns

This project is intended as both a real-world backend system and a **portfolio-quality reference implementation

---

📬 Contact

Chandra Sekhar Vipparla
📧 Email: code.chandrasekhar@gmail.com
🔗 LinkedIn: https://www.linkedin.com/in/chandra-sekhar-vipparla/