Loans

Description

The Loan entity represents an active or completed installment loan. Loans are created when a user accepts a loan application and funds are disbursed. Each loan has an associated set of installments that define the repayment schedule.

Storage

Environment Table Name Region

test

test-loc-service

us-west-2

prod

prod-loc-service

us-east-2

Fields

Field Type Description

loc_user_id

String

User ID who owns the loan

loc_loan_id

String

Unique loan identifier (UUID)

loc_loan_application_id

String

Reference to the originating loan application

loc_loan_number

String

Human-readable loan number (e.g., "FM-000001")

loc_loan_amount

Integer

Principal loan amount in cents

loc_origination_fee

Integer

Origination fee amount in cents

loc_fee_percent

Float

Origination fee as a percentage

loc_fee_type

String

Fee type: fixed or percentage

loc_total_amount

Integer

Total amount owed (principal + fee) in cents

loc_amount_disbursed

Integer

Amount sent to user (total - fee) in cents

loc_outstanding_balance

Integer

Current remaining balance in cents

loc_status

String

Loan status: OPEN, CLOSED, DEFAULTED

loc_repayment_cadence

String

Payment frequency: biweekly

loc_disbursement_date

String

Date funds were sent to user (RFC3339)

loc_disbursement_method

String

Method used: ach or pinless

loc_completion_date

String

Date loan was fully paid off (RFC3339)

loc_account_last_four

String

Last 4 digits of disbursement account

loc_confirmation_id

String

Disbursement confirmation ID from payments service

auto_pay_enabled

Boolean

Whether autopay is enabled for this loan

loc_created_date

String

Creation timestamp (RFC3339)

loc_last_updated

String

Last update timestamp (RFC3339)

Keys and Indexes

Primary Key

Key Pattern

PK

USER#<user_id>

SK

LOAN#<loan_id>

GSI1 - Loans by User and Status

Used to list all loans for a user in a specific status.

Key Pattern

GSI1PK

USER#<user_id>#STATUS#<loan_status>

GSI1SK

LOAN#DATE#<created_date>#LOAN#<loan_id>

GSI2 - Loans by User and Date

Used to list all loans for a user ordered by creation date.

Key Pattern

GSI2PK

USER#<user_id>

GSI2SK

LOAN#DATE#<created_date>#LOAN#<loan_id>

GSI3 - Loans by Application ID

Used to look up a loan by its originating application.

Key Pattern

GSI3PK

USER#<user_id>

GSI3SK

LOAN#LOANAPP#<loan_application_id>

Query Patterns

Query Index Key Condition Sort Key Condition

Get loan by user and loan ID

Primary

PK = USER#<user_id>

SK = LOAN#<loan_id>

List all loans for a user

GSI2

GSI2PK = USER#<user_id>

GSI2SK begins_with LOAN#DATE#

List loans for user in status

GSI1

GSI1PK = USER#<user_id>#STATUS#<status>

GSI1SK begins_with LOAN#DATE#

Get loan by application ID

GSI3

GSI3PK = USER#<user_id>

GSI3SK = LOAN#LOANAPP#<application_id>

Status Transitions

                    ┌──────────────────────┐
                    │        OPEN          │
                    │  (Active loan with   │
                    │  outstanding balance)│
                    └──────────┬───────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
              ▼                ▼                ▼
     ┌────────────────┐  ┌──────────┐  ┌────────────────┐
     │     CLOSED     │  │ DEFAULTED│  │     OPEN       │
     │ (Fully paid)   │  │ (Default)│  │   (Ongoing)    │
     └────────────────┘  └──────────┘  └────────────────┘

Related Entities