# syed-mohsin-raza/meridian-lms architecture

> Architecture diagram of the GitHub repository syed-mohsin-raza/meridian-lms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/syed-mohsin-raza/meridian-lms
- Repository: https://github.com/syed-mohsin-raza/meridian-lms

## Overview

Meridian LMS is a loan-management platform with customer and staff portals backed by a Spring Boot API. Customers register or sign in, apply for loans, track repayment schedules and make payments; staff review applications, manage employees and permissions, and monitor analytics. The backend also provides audit views and AI-generated credit-risk narratives, with template fallback when AI is unavailable. The graph emphasizes documented workflows and sampled call ownership; several controller, service, and analytics internals are represented at their tree paths because their source was not sampled.

Main entry points: [`frontend/src/lib/api/client.ts`](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/lib/api/client.ts) (HTTP API client), [`backend/src/main/java/com/meridian/lms/service/LoanService.java`](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/LoanService.java) (Loan application and review), [`backend/src/main/java/com/meridian/lms/service/PaymentService.java`](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/PaymentService.java) (Payment processing), [`backend/src/main/java/com/meridian/lms/ai/SpringAiCreditRiskNarrativeService.java`](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/ai/SpringAiCreditRiskNarrativeService.java) (Risk narrative generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portals["Web portals"]
  node_customer_pages["Customer loan pages<br/>[page.tsx]"]
  node_admin_pages["Staff loan pages<br/>[page.tsx]"]
  node_payment_pages["Payment pages<br/>[page.tsx]"]
  node_auth_pages["Login and registration<br/>[page.tsx]"]
  node_api_client["HTTP API client<br/>[client.ts]"]
  node_loans_api["Loan API calls<br/>[loans.ts]"]
  node_payments_api["Payment API calls<br/>[payments.ts]"]
  node_auth_api["Authentication API calls<br/>[auth.ts]"]
end

subgraph group_api["API and identity"]
  node_loan_controller["Loan endpoints"]
  node_payment_controller["Payment endpoints"]
  node_auth_controller["Authentication endpoints"]
  node_auth_service["Authentication service<br/>[AuthService.java]"]
  node_jwt_service["JWT service<br/>[JwtService.java]"]
  node_user_repository["User repository"]
  node_employee_service["Employee and permission management"]
end

subgraph group_lending["Lending operations"]
  node_loan_service["Loan application and review<br/>[LoanService.java]"]
  node_payment_service["Payment processing"]
  node_loan_repository["Loan repository"]
  node_payment_repository["Payment repository"]
  node_loan_type_service["Loan type rules"]
  node_credit_score["Credit score updates"]
  node_database[("PostgreSQL")]
end

subgraph group_insights["Insights and oversight"]
  node_analytics["Analytics"]
  node_audit["Audit history<br/>[AuditService.java]"]
  node_ai_controller["Risk narrative endpoint<br/>[AiController.java]"]
  node_ai_service["Risk narrative generation"]
  node_profile_aggregator["Credit profile aggregation"]
  node_narrative_cache["Narrative cache"]
  node_fallback["Template fallback"]
end

node_customer(("Customer"))
node_staff(("Admin or employee"))
node_ai_provider{{"AI model provider"}}
node_redis[("Redis cache")]

node_customer -->|"uses"| node_customer_pages
node_staff -->|"uses"| node_admin_pages
node_customer_pages -->|"requests"| node_loans_api
node_admin_pages -->|"requests"| node_loans_api
node_payment_pages -->|"requests"| node_payments_api
node_auth_pages -->|"submits credentials"| node_auth_api
node_loans_api -->|"calls"| node_api_client
node_payments_api -->|"calls"| node_api_client
node_auth_api -->|"calls"| node_api_client
node_api_client -->|"HTTP requests"| node_loan_controller
node_api_client -->|"HTTP requests"| node_payment_controller
node_api_client -->|"HTTP requests"| node_auth_controller
node_loan_controller -->|"dispatches"| node_loan_service
node_payment_controller -->|"dispatches"| node_payment_service
node_auth_controller -->|"dispatches"| node_auth_service
node_auth_service -->|"reads and writes"| node_user_repository
node_auth_service -->|"issues token"| node_jwt_service
node_loan_service -->|"reads and writes"| node_loan_repository
node_loan_service -->|"loads loan rules"| node_loan_type_service
node_loan_service -->|"saves schedule"| node_payment_repository
node_loan_service -->|"updates score"| node_credit_score
node_payment_service -->|"reads and writes"| node_payment_repository
node_payment_service -->|"loads loan"| node_loan_repository
node_payment_service -->|"updates score"| node_credit_score
node_loan_repository -->|"persists loan data"| node_database
node_payment_repository -->|"persists payment data"| node_database
node_user_repository -->|"persists user data"| node_database
node_staff -->|"manages staff"| node_employee_service
node_employee_service -->|"reads and writes"| node_user_repository
node_staff -->|"views metrics"| node_analytics
node_staff -->|"views audit history"| node_audit
node_customer -->|"requests risk narrative"| node_ai_controller
node_ai_controller -->|"builds credit profile"| node_profile_aggregator
node_ai_controller -->|"requests narrative"| node_ai_service
node_ai_service -->|"checks and stores"| node_narrative_cache
node_narrative_cache -->|"cache access"| node_redis
node_ai_service -.->|"generates narrative"| node_ai_provider
node_ai_service -->|"builds fallback"| node_fallback

click node_customer_pages "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/app/(customer)/loans/apply/page.tsx"
click node_admin_pages "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/app/admin/loans/page.tsx"
click node_payment_pages "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/app/(customer)/payments/page.tsx"
click node_auth_pages "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/app/(auth)/login/page.tsx"
click node_api_client "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/lib/api/client.ts"
click node_loans_api "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/lib/api/loans.ts"
click node_payments_api "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/lib/api/payments.ts"
click node_auth_api "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/lib/api/auth.ts"
click node_loan_controller "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/controller/LoanController.java"
click node_payment_controller "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/controller/PaymentController.java"
click node_auth_controller "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/controller/AuthController.java"
click node_auth_service "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/AuthService.java"
click node_jwt_service "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/security/JwtService.java"
click node_user_repository "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/repository/UserRepository.java"
click node_loan_service "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/LoanService.java"
click node_payment_service "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/PaymentService.java"
click node_loan_repository "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/repository/LoanRepository.java"
click node_payment_repository "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/repository/PaymentRepository.java"
click node_loan_type_service "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/LoanTypeService.java"
click node_credit_score "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/CreditScoreService.java"
click node_employee_service "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/EmployeeService.java"
click node_analytics "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/AnalyticsService.java"
click node_audit "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/AuditService.java"
click node_ai_controller "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/controller/AiController.java"
click node_ai_service "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/ai/SpringAiCreditRiskNarrativeService.java"
click node_profile_aggregator "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/ai/CreditProfileAggregator.java"
click node_narrative_cache "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/ai/CreditRiskNarrativeCache.java"
click node_fallback "https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/ai/FallbackNarrativeBuilder.java"

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_customer_pages,node_admin_pages,node_payment_pages,node_auth_pages,node_api_client,node_loans_api,node_payments_api,node_auth_api toneBlue
class node_loan_controller,node_payment_controller,node_auth_controller,node_auth_service,node_jwt_service,node_user_repository,node_employee_service,node_redis toneAmber
class node_loan_service,node_payment_service,node_loan_repository,node_payment_repository,node_loan_type_service,node_credit_score,node_database toneMint
class node_analytics,node_audit,node_ai_controller,node_ai_service,node_profile_aggregator,node_narrative_cache,node_fallback toneRose
class node_customer,node_staff,node_ai_provider toneIndigo
```

## Components

### Web portals

- [Customer loan pages](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/app/(customer)/loans/apply/page.tsx): `frontend/src/app/(customer)/loans/apply/page.tsx`
- [Staff loan pages](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/app/admin/loans/page.tsx): `frontend/src/app/admin/loans/page.tsx`
- [Payment pages](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/app/(customer)/payments/page.tsx): `frontend/src/app/(customer)/payments/page.tsx`
- [Login and registration](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/app/(auth)/login/page.tsx): `frontend/src/app/(auth)/login/page.tsx`
- [HTTP API client](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/lib/api/client.ts): `frontend/src/lib/api/client.ts`
- [Loan API calls](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/lib/api/loans.ts): `frontend/src/lib/api/loans.ts`
- [Payment API calls](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/lib/api/payments.ts): `frontend/src/lib/api/payments.ts`
- [Authentication API calls](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/frontend/src/lib/api/auth.ts): `frontend/src/lib/api/auth.ts`

### API and identity

- [Loan endpoints](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/controller/LoanController.java): `backend/src/main/java/com/meridian/lms/controller/LoanController.java`
- [Payment endpoints](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/controller/PaymentController.java): `backend/src/main/java/com/meridian/lms/controller/PaymentController.java`
- [Authentication endpoints](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/controller/AuthController.java): `backend/src/main/java/com/meridian/lms/controller/AuthController.java`
- [Authentication service](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/AuthService.java): `backend/src/main/java/com/meridian/lms/service/AuthService.java`
- [JWT service](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/security/JwtService.java): `backend/src/main/java/com/meridian/lms/security/JwtService.java`
- [User repository](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/repository/UserRepository.java): `backend/src/main/java/com/meridian/lms/repository/UserRepository.java`
- [Employee and permission management](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/EmployeeService.java): `backend/src/main/java/com/meridian/lms/service/EmployeeService.java`

### Lending operations

- [Loan application and review](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/LoanService.java): `backend/src/main/java/com/meridian/lms/service/LoanService.java`
- [Payment processing](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/PaymentService.java): `backend/src/main/java/com/meridian/lms/service/PaymentService.java`
- [Loan repository](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/repository/LoanRepository.java): `backend/src/main/java/com/meridian/lms/repository/LoanRepository.java`
- [Payment repository](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/repository/PaymentRepository.java): `backend/src/main/java/com/meridian/lms/repository/PaymentRepository.java`
- [Loan type rules](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/LoanTypeService.java): `backend/src/main/java/com/meridian/lms/service/LoanTypeService.java`
- [Credit score updates](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/CreditScoreService.java): `backend/src/main/java/com/meridian/lms/service/CreditScoreService.java`
- **PostgreSQL**

### Insights and oversight

- [Analytics](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/AnalyticsService.java): `backend/src/main/java/com/meridian/lms/service/AnalyticsService.java`
- [Audit history](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/service/AuditService.java): `backend/src/main/java/com/meridian/lms/service/AuditService.java`
- [Risk narrative endpoint](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/controller/AiController.java): `backend/src/main/java/com/meridian/lms/controller/AiController.java`
- [Risk narrative generation](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/ai/SpringAiCreditRiskNarrativeService.java): `backend/src/main/java/com/meridian/lms/ai/SpringAiCreditRiskNarrativeService.java`
- [Credit profile aggregation](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/ai/CreditProfileAggregator.java): `backend/src/main/java/com/meridian/lms/ai/CreditProfileAggregator.java`
- [Narrative cache](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/ai/CreditRiskNarrativeCache.java): `backend/src/main/java/com/meridian/lms/ai/CreditRiskNarrativeCache.java`
- [Template fallback](https://github.com/syed-mohsin-raza/meridian-lms/blob/main/backend/src/main/java/com/meridian/lms/ai/FallbackNarrativeBuilder.java): `backend/src/main/java/com/meridian/lms/ai/FallbackNarrativeBuilder.java`

### Other components

- **Customer**
- **Admin or employee**
- **AI model provider**
- **Redis cache**

## Connections

- Customer → Customer loan pages: uses
- Admin or employee → Staff loan pages: uses
- Customer loan pages → Loan API calls: requests
- Staff loan pages → Loan API calls: requests
- Payment pages → Payment API calls: requests
- Login and registration → Authentication API calls: submits credentials
- Loan API calls → HTTP API client: calls
- Payment API calls → HTTP API client: calls
- Authentication API calls → HTTP API client: calls
- HTTP API client → Loan endpoints: HTTP requests
- HTTP API client → Payment endpoints: HTTP requests
- HTTP API client → Authentication endpoints: HTTP requests
- Loan endpoints → Loan application and review: dispatches
- Payment endpoints → Payment processing: dispatches
- Authentication endpoints → Authentication service: dispatches
- Authentication service → User repository: reads and writes
- Authentication service → JWT service: issues token
- Loan application and review → Loan repository: reads and writes
- Loan application and review → Loan type rules: loads loan rules
- Loan application and review → Payment repository: saves schedule
- Loan application and review → Credit score updates: updates score
- Payment processing → Payment repository: reads and writes
- Payment processing → Loan repository: loads loan
- Payment processing → Credit score updates: updates score
- Loan repository → PostgreSQL: persists loan data
- Payment repository → PostgreSQL: persists payment data
- User repository → PostgreSQL: persists user data
- Admin or employee → Employee and permission management: manages staff
- Employee and permission management → User repository: reads and writes
- Admin or employee → Analytics: views metrics
- Admin or employee → Audit history: views audit history
- Customer → Risk narrative endpoint: requests risk narrative
- Risk narrative endpoint → Credit profile aggregation: builds credit profile
- Risk narrative endpoint → Risk narrative generation: requests narrative
- Risk narrative generation → Narrative cache: checks and stores
- Narrative cache → Redis cache: cache access
- Risk narrative generation → AI model provider: generates narrative
- Risk narrative generation → Template fallback: builds fallback