Loan Projection Engine

Backend-first loan amortization and repayment forecasting API built with Java 26, Spring Boot 4, PostgreSQL, Flyway, and OpenAPI.

This project is designed as a portfolio-grade finance backend that demonstrates how to build a production-style loan calculation engine with clean architecture, persistent scenarios, export support, and realistic repayment modelling. It is intentionally API-first, so Swagger UI is the primary interface instead of an Angular frontend.

Why This Project Exists

Recruiters and engineering teams often see simple CRUD demos. This repository aims to show stronger backend engineering skills through:

• deterministic financial calculations with BigDecimal
• explicit domain modelling for loan schedules and rate changes
• clean package boundaries across api, application, domain, infrastructure, and config
• Flyway-managed schema evolution
• meaningful automated tests across domain logic and Spring MVC integration
• export workflows that make the project demo-friendly without building a UI

Core Features

• create and persist loan projections
• generate full amortization schedules
• support monthly, weekly, and biweekly repayment frequencies
• model one-time extra payments
• model recurring extra payments
• apply variable interest-rate adjustments over time
• support multiple repricing strategies, including capped payment increases
• compare multiple loan scenarios against a baseline
• export persisted projections as CSV or PDF
• explore and test the API through Swagger UI

Example Scenarios

• How much interest will I pay on a 60-month personal loan?
• What happens if I make a lump-sum payment after month 12?
• How much faster does the loan close if I pay an extra amount every two weeks?
• What happens when the rate changes but payment growth is capped?
• Which of two repayment strategies produces the lower total cost?

Tech Stack

• Java 26
• Spring Boot 4.1
• Spring Data JPA
• PostgreSQL
• Flyway
• springdoc OpenAPI / Swagger UI
• PDFBox
• JUnit 5
• Mockito
• Testcontainers
• Docker Compose

Architecture

The main engineering value lives in the calculation and orchestration layers rather than the controller layer.

• api REST controllers, request DTOs, response DTOs, and export options
• application use-case orchestration, persistence coordination, export generation
• domain amortization logic, repayment frequency rules, extra-payment behaviour, repricing strategies
• infrastructure JPA entities and repositories
• config OpenAPI and application configuration

Running Locally

1. Start PostgreSQL:

docker compose up -d

2. Start the application:

mvn spring-boot:run

3. Open Swagger UI:

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

Configuration

Default local settings are defined in src/main/resources/application.yml.

Environment variables you can override:

• DB_URL
• DB_USERNAME
• DB_PASSWORD

API Endpoints

• POST /api/v1/loan-projections
• GET /api/v1/loan-projections/{projectionId}
• GET /api/v1/loan-projections/{projectionId}/schedule
• GET /api/v1/loan-projections/{projectionId}/export?format=CSV
• GET /api/v1/loan-projections/{projectionId}/export?format=PDF
• POST /api/v1/loan-projections/compare

Sample Request

{
  "customerName": "Portfolio Demo",
  "principal": 250000.00,
  "annualInterestRate": 11.75,
  "termMonths": 60,
  "repaymentFrequency": "MONTHLY",
  "startDate": "2026-07-01",
  "originationFee": 1200.00,
  "monthlyServiceFee": 69.00,
  "extraPayments": [
    {
      "paymentDate": "2027-07-01",
      "amount": 15000.00
    }
  ],
  "recurringExtraPayments": [
    {
      "startDate": "2026-10-01",
      "endDate": "2027-10-01",
      "amount": 500.00,
      "recurrenceFrequency": "MONTHLY"
    }
  ],
  "interestRateAdjustments": [
    {
      "effectiveDate": "2028-01-01",
      "annualInterestRate": 13.25,
      "strategy": "RECALCULATE_PAYMENT_WITH_CAP",
      "paymentChangeCapPercent": 8.00
    }
  ]
}

Swagger-First Demo Flow

1. Create a projection with POST /api/v1/loan-projections
2. Inspect the summary and payoff date
3. Open the stored schedule with GET /api/v1/loan-projections/{projectionId}/schedule
4. Export the result as CSV or PDF
5. Compare alternative repayment scenarios with POST /api/v1/loan-projections/compare

Testing

Run the required checks with:

mvn clean verify
mvn test

Notes:

• the default test profile uses H2 in PostgreSQL compatibility mode for fast feedback
• Swagger endpoints are disabled in tests to keep the test runtime quieter and closer to focused application behaviour
• a PostgreSQL-backed migration validation test is included for stronger schema confidence when Docker is available

Future Enhancements

• authentication and role-based access control
• versioned projection history
• event publication for downstream ledger systems
• repayment holiday support
• richer PDF formatting for customer-style statements
• eventual Angular dashboard in a separate UI repository

License

MIT