# harg-15/loanlens architecture

> Architecture diagram of the GitHub repository harg-15/loanlens, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harg-15/loanlens
- Repository: https://github.com/harg-15/loanlens

## Overview

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.

Main entry points: [`src/main/java/com/loanlens/exception/GlobalExceptionHandler.java`](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/exception/GlobalExceptionHandler.java) (Error handler), [`src/main/java/com/loanlens/dto/response`](https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/dto/response) (Response DTOs), [`src/main/java/com/loanlens/entity`](https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/entity) (Domain entities), [`src/main/java/com/loanlens/repository`](https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/repository) (Repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API layer"]
  node_auth_controller["Auth API<br/>REST controller"]
  node_borrower_controller["Borrower API<br/>REST controller"]
  node_loan_controller["Loan API<br/>REST controller"]
  node_repayment_controller["Repayment API<br/>REST controller"]
  node_portfolio_controller["Portfolio API<br/>REST controller"]
  node_riskalert_controller["Alert API<br/>REST controller"]
  node_request_dtos["Request DTOs<br/>HTTP contracts"]
  node_response_dtos["Response DTOs<br/>HTTP contracts"]
end

subgraph group_core["Core services"]
  node_auth_service["Auth service<br/>application service<br/>[AuthService.java]"]
  node_borrower_service["Borrower service<br/>application service"]
  node_loan_service["Loan service<br/>application service<br/>[LoanService.java]"]
  node_repayment_service["Repayment service<br/>application service"]
  node_portfolio_service["Portfolio service<br/>application service"]
  node_riskalert_service["Alert service<br/>application service"]
  node_scoring_engine{{"Scoring engine<br/>risk engine<br/>[ScoringEngine.java]"}}
  node_scoring_strategies["Strategies<br/>risk rules"]
end

subgraph group_data["Data model"]
  node_entities[("Domain entities<br/>JPA model")]
  node_repositories["Repositories<br/>Spring Data JPA"]
end

subgraph group_platform["Platform"]
  node_security_config["Security config<br/>JWT security"]
  node_jwt_service["JWT service<br/>token service<br/>[JwtService.java]"]
  node_user_details["User details<br/>auth adapter"]
  node_jwt_filter["JWT filter<br/>auth filter<br/>[JwtAuthFilter.java]"]
  node_exception_handler["Error handler<br/>exception mapping"]
  node_schedulers["Schedulers<br/>background jobs"]
end

node_auth_controller -->|"accepts"| node_request_dtos
node_borrower_controller -->|"accepts"| node_request_dtos
node_loan_controller -->|"accepts"| node_request_dtos
node_repayment_controller -->|"accepts"| node_request_dtos
node_auth_controller -->|"returns"| node_response_dtos
node_borrower_controller -->|"returns"| node_response_dtos
node_loan_controller -->|"returns"| node_response_dtos
node_repayment_controller -->|"returns"| node_response_dtos
node_portfolio_controller -->|"returns"| node_response_dtos
node_riskalert_controller -->|"returns"| node_response_dtos
node_auth_controller -->|"calls"| node_auth_service
node_borrower_controller -->|"calls"| node_borrower_service
node_loan_controller -->|"calls"| node_loan_service
node_repayment_controller -->|"calls"| node_repayment_service
node_portfolio_controller -->|"calls"| node_portfolio_service
node_riskalert_controller -->|"calls"| node_riskalert_service
node_auth_service -->|"uses"| node_user_details
node_auth_service -->|"uses"| node_jwt_service
node_security_config -->|"installs"| node_jwt_filter
node_security_config -->|"uses"| node_jwt_service
node_security_config -->|"uses"| node_user_details
node_loan_service -->|"persists via"| node_repositories
node_repayment_service -->|"persists via"| node_repositories
node_borrower_service -->|"persists via"| node_repositories
node_portfolio_service -->|"persists via"| node_repositories
node_riskalert_service -->|"persists via"| node_repositories
node_scoring_engine -->|"composes"| node_scoring_strategies
node_schedulers -->|"triggers"| node_scoring_engine
node_schedulers -->|"triggers"| node_portfolio_service
node_scoring_engine -->|"feeds"| node_riskalert_service
node_loan_service -->|"reads/writes"| node_entities
node_repayment_service -->|"reads/writes"| node_entities
node_portfolio_service -->|"reads/writes"| node_entities
node_riskalert_service -->|"reads/writes"| node_entities
node_borrower_service -->|"reads/writes"| node_entities
node_auth_service -->|"reads/writes"| node_entities
node_exception_handler -.->|"handles"| node_auth_controller
node_exception_handler -.->|"handles"| node_borrower_controller
node_exception_handler -.->|"handles"| node_loan_controller
node_exception_handler -.->|"handles"| node_repayment_controller
node_exception_handler -.->|"handles"| node_portfolio_controller
node_exception_handler -.->|"handles"| node_riskalert_controller

click node_auth_controller "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/controller/AuthController.java"
click node_borrower_controller "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/controller/BorrowerController.java"
click node_loan_controller "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/controller/LoanController.java"
click node_repayment_controller "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/controller/RepaymentController.java"
click node_portfolio_controller "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/controller/PortfolioController.java"
click node_riskalert_controller "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/controller/RiskAlertController.java"
click node_request_dtos "https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/dto/request"
click node_response_dtos "https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/dto/response"
click node_auth_service "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/service/AuthService.java"
click node_borrower_service "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/service/BorrowerService.java"
click node_loan_service "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/service/LoanService.java"
click node_repayment_service "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/service/RepaymentService.java"
click node_portfolio_service "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/service/PortfolioService.java"
click node_riskalert_service "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/service/RiskAlertService.java"
click node_scoring_engine "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/scoring/ScoringEngine.java"
click node_scoring_strategies "https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/scoring/strategies"
click node_entities "https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/entity"
click node_repositories "https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/repository"
click node_security_config "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/security/SecurityConfig.java"
click node_jwt_service "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/security/JwtService.java"
click node_user_details "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/security/UserDetailsServiceImpl.java"
click node_jwt_filter "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/security/JwtAuthFilter.java"
click node_exception_handler "https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/exception/GlobalExceptionHandler.java"
click node_schedulers "https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/scheduler"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth_controller,node_borrower_controller,node_loan_controller,node_repayment_controller,node_portfolio_controller,node_riskalert_controller,node_request_dtos,node_response_dtos toneBlue
class node_auth_service,node_borrower_service,node_loan_service,node_repayment_service,node_portfolio_service,node_riskalert_service,node_scoring_engine,node_scoring_strategies toneAmber
class node_entities,node_repositories toneMint
class node_security_config,node_jwt_service,node_user_details,node_jwt_filter,node_exception_handler,node_schedulers toneRose
```

## Components

### API layer

REST boundary and request/response DTOs

- [Auth API](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/controller/AuthController.java): REST controller · Login and registration endpoints · `src/main/java/com/loanlens/controller/AuthController.java`
- [Borrower API](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/controller/BorrowerController.java): REST controller · Borrower management endpoints · `src/main/java/com/loanlens/controller/BorrowerController.java`
- [Loan API](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/controller/LoanController.java): REST controller · Loan lifecycle endpoints · `src/main/java/com/loanlens/controller/LoanController.java`
- [Repayment API](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/controller/RepaymentController.java): REST controller · Repayment posting endpoints · `src/main/java/com/loanlens/controller/RepaymentController.java`
- [Portfolio API](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/controller/PortfolioController.java): REST controller · Portfolio summary endpoints · `src/main/java/com/loanlens/controller/PortfolioController.java`
- [Alert API](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/controller/RiskAlertController.java): REST controller · Risk alert query endpoints · `src/main/java/com/loanlens/controller/RiskAlertController.java`
- [Request DTOs](https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/dto/request): HTTP contracts · Inbound API request models · `src/main/java/com/loanlens/dto/request`
- [Response DTOs](https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/dto/response): HTTP contracts · Outbound API response models · `src/main/java/com/loanlens/dto/response`

### Core services

Business orchestration and risk processing

- [Auth service](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/service/AuthService.java): application service · Authentication and registration flows · `src/main/java/com/loanlens/service/AuthService.java`
- [Borrower service](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/service/BorrowerService.java): application service · Borrower business rules · `src/main/java/com/loanlens/service/BorrowerService.java`
- [Loan service](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/service/LoanService.java): application service · Loan creation and servicing logic · `src/main/java/com/loanlens/service/LoanService.java`
- [Repayment service](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/service/RepaymentService.java): application service · Repayment posting and allocation · `src/main/java/com/loanlens/service/RepaymentService.java`
- [Portfolio service](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/service/PortfolioService.java): application service · Portfolio summaries and snapshots · `src/main/java/com/loanlens/service/PortfolioService.java`
- [Alert service](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/service/RiskAlertService.java): application service · Risk alert lifecycle management · `src/main/java/com/loanlens/service/RiskAlertService.java`
- [Scoring engine](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/scoring/ScoringEngine.java): risk engine · Combines scoring strategies into risk outputs · `src/main/java/com/loanlens/scoring/ScoringEngine.java`
- [Strategies](https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/scoring/strategies): risk rules · Payment timeliness, overdue streak, partial payment, principal · `src/main/java/com/loanlens/scoring/strategies`

### Data model

Persistent entities and repositories

- [Domain entities](https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/entity): JPA model · Borrower, loan, repayment, alert, and snapshot state · `src/main/java/com/loanlens/entity`
- [Repositories](https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/repository): Spring Data JPA · Persistence interfaces for major entities · `src/main/java/com/loanlens/repository`

### Platform

Security, scheduling, configuration, and error handling

- [Security config](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/security/SecurityConfig.java): JWT security · Filter chain and OpenAPI wiring · `src/main/java/com/loanlens/security/SecurityConfig.java`
- [JWT service](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/security/JwtService.java): token service · Token creation and validation · `src/main/java/com/loanlens/security/JwtService.java`
- [User details](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/security/UserDetailsServiceImpl.java): auth adapter · Loads users for Spring Security · `src/main/java/com/loanlens/security/UserDetailsServiceImpl.java`
- [JWT filter](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/security/JwtAuthFilter.java): auth filter · Stateless request authentication · `src/main/java/com/loanlens/security/JwtAuthFilter.java`
- [Error handler](https://github.com/harg-15/loanlens/blob/main/src/main/java/com/loanlens/exception/GlobalExceptionHandler.java): exception mapping · Centralized API error responses · `src/main/java/com/loanlens/exception/GlobalExceptionHandler.java`
- [Schedulers](https://github.com/harg-15/loanlens/tree/main/src/main/java/com/loanlens/scheduler): background jobs · Periodic scoring and portfolio snapshot jobs · `src/main/java/com/loanlens/scheduler`

## Connections

- Auth API → Request DTOs: accepts · Login and registration payloads
- Borrower API → Request DTOs: accepts · Borrower create/update payloads
- Loan API → Request DTOs: accepts · Loan request payloads
- Repayment API → Request DTOs: accepts · Repayment request payloads
- Auth API → Response DTOs: returns · Auth responses
- Borrower API → Response DTOs: returns · Borrower responses
- Loan API → Response DTOs: returns · Loan and installment responses
- Repayment API → Response DTOs: returns · Repayment responses
- Portfolio API → Response DTOs: returns · Portfolio summaries
- Alert API → Response DTOs: returns · Risk alert responses
- Auth API → Auth service: calls · Authentication flow
- Borrower API → Borrower service: calls · Borrower management
- Loan API → Loan service: calls · Loan orchestration
- Repayment API → Repayment service: calls · Repayment processing
- Portfolio API → Portfolio service: calls · Portfolio reporting
- Alert API → Alert service: calls · Alert querying and management
- Auth service → User details: uses · Loads authenticated users
- Auth service → JWT service: uses · Issues and validates tokens
- Security config → JWT filter: installs · Stateless auth filter
- Security config → JWT service: uses · Token handling
- Security config → User details: uses · Security user lookup
- Loan service → Repositories: persists via · Loan and installment data access
- Repayment service → Repositories: persists via · Repayment data access
- Borrower service → Repositories: persists via · Borrower data access
- Portfolio service → Repositories: persists via · Portfolio snapshot access
- Alert service → Repositories: persists via · Risk alert access
- Scoring engine → Strategies: composes · Applies scoring rules
- Schedulers → Scoring engine: triggers · Periodic loan re-scoring
- Schedulers → Portfolio service: triggers · Periodic portfolio snapshots
- Scoring engine → Alert service: feeds · Produces alert-worthy risk outputs
- Loan service → Domain entities: reads/writes · Loan domain state
- Repayment service → Domain entities: reads/writes · Repayment and installment state
- Portfolio service → Domain entities: reads/writes · Snapshot and portfolio state
- Alert service → Domain entities: reads/writes · Risk alert state
- Borrower service → Domain entities: reads/writes · Borrower state
- Auth service → Domain entities: reads/writes · User and role state
- Error handler → Auth API: handles · Controller error mapping
- Error handler → Borrower API: handles · Controller error mapping
- Error handler → Loan API: handles · Controller error mapping
- Error handler → Repayment API: handles · Controller error mapping
- Error handler → Portfolio API: handles · Controller error mapping
- Error handler → Alert API: handles · Controller error mapping