harg-15/loanlens

1. Overall shape

LoanLens is a single Spring Boot 3.2 backend monolith. Its core architecture is a conventional layered design: REST controllers expose the API, service classes hold business logic, Spring Data JPA repositories persist data, and JPA entities model the loan domain in PostgreSQL.

2. Request/response boundary

All external interaction enters through the controllers under com.loanlens.controller. The API is organized by business area: authentication, borrowers, loans, repayments, portfolio reporting, and risk alerts. DTOs in com.loanlens.dto.request and com.loanlens.dto.response isolate the HTTP contract from the persistence model.

3. Domain model

The main persisted entities are User, Borrower, Loan, LoanInstallment, Repayment, RiskAlert, and PortfolioSnapshot. These represent the operational loan system, the repayment lifecycle, the computed alert state, and historical portfolio snapshots used for monitoring.

4. Business service layer

Services in com.loanlens.service are the primary orchestration layer. They connect incoming controller requests to repositories, enforce domain rules, and shape responses. This is where the application likely coordinates loan creation, repayment posting, borrower management, portfolio summaries, and alert generation.

5. Persistence layer

Repositories in com.loanlens.repository are Spring Data JPA interfaces for each major entity. PostgreSQL is the production datastore, while tests use H2 as an in-memory replacement. The repository layer is the only boundary that should directly talk to the database.

6. Authentication and authorization

Security is JWT-based and stateless. JwtAuthFilter, JwtService, UserDetailsServiceImpl, and SecurityConfig form the authentication boundary, while AuthController and AuthService handle login and registration flows. The presence of Role suggests role-based access control over the loan and risk operations.

7. Risk scoring subsystem

The scoring subsystem is separated from the standard CRUD flow. ScoringEngine applies a set of ScoringStrategy implementations such as payment timeliness, overdue streak, partial payment behavior, and outstanding principal. This produces risk-related outputs that feed alerting and portfolio monitoring.

8. Scheduled background processing

Two schedulers run periodic jobs outside the request/response cycle: ScoringScheduler and PortfolioSnapshotScheduler. These background tasks likely re-evaluate loans for risk and persist snapshots of portfolio health, making the system proactive rather than purely transactional.

9. Early warning and alerting

Risk alerts are a first-class part of the domain, with dedicated RiskAlert entities, repository, service, and controller. This indicates a separate lifecycle for generated alerts: they are produced by scoring/scheduled jobs, stored, and then queried or managed through the API.

10. API documentation and operational setup

OpenApiConfig integrates Swagger/OpenAPI, so the service exposes machine-readable and interactive API docs. Runtime configuration comes from application.properties plus environment variables in .env.example, including database credentials, JWT secret/expiration, and default admin credentials.

11. Error handling

GlobalExceptionHandler centralizes error-to-response mapping, with explicit exceptions for bad requests and missing resources. This keeps failure handling consistent across all controllers and prevents domain errors from leaking directly to clients.

12. Test boundary

The test setup is lightweight and backend-focused: LoanLensApplicationTests plus H2-backed test properties validate the Spring context and likely core flows without needing PostgreSQL. This reinforces that the important architectural seams are the REST API, service layer, security layer, and scheduled scoring pipeline.