Skip to content

Portfolio Management

The apps.portfolio module manages loan groupings, performance snapshots, investor assignments, and loan tape generation.

Portfolios

Portfolios are named groupings of loans for tracking and reporting purposes:

Field Description
name Portfolio name (e.g., "Q1 2026 Consumer Installment")
description Description and notes
program Optional FK to lending program (scope to one program)
status open, closed, or sold
criteria JSONB rules for dynamic loan inclusion

Static vs. Dynamic Assignment

  • Static: Loans are manually assigned to a portfolio via API
  • Dynamic: Loans are automatically included based on criteria rules matching loan attributes (product, origination date, balance range, etc.)

Portfolio Status

Status Description
open Accepting new loans, active management
closed No new loans, still tracked
sold Portfolio sold/transferred to investor

Auto-Assignment

A daily Celery task (5:00 AM) evaluates unassigned loans against portfolio criteria and assigns matches automatically.

Snapshots

Point-in-time portfolio metrics captured daily via Celery:

Metric Description
total_balance Total principal outstanding
interest_receivable Total accrued interest
delinquent_amount Total delinquent balance
loan_count Number of loans in portfolio
weighted_avg_rate Weighted average interest rate
bucket_breakdown Delinquency bucket counts (JSONB)
irr Internal rate of return (computed via XIRR)
moic Multiple on invested capital
total_disbursed Total amount disbursed
total_collected Total payments collected

Snapshots enable trend analysis and performance monitoring over time. Snapshot generation uses Celery groups for parallel processing across portfolios.

Investors

Investor entities that purchase or fund loan portfolios:

Field Description
name Investor name
investor_type Individual, institutional, fund, etc.
Bank account details For distribution payments
Contact information Phone, email, address

Loan Assignments

The LoanAssignment model tracks which investor owns which loans:

Field Description
loan FK to loan
investor FK to investor
assignment_date When the assignment was made
purchase_price Price paid for the loan

Loan Tape Generation

Loan tapes are standardized data exports for investor reporting:

Loan Tape Config

Field Description
name Configuration name
portfolio FK to portfolio
tape_format Output format (CSV, XLSX)
tape_schedule Generation frequency
required_fields JSONB list of fields to include
recipient_email Where to send generated tapes

Loan tapes contain loan-level detail (balances, rates, statuses, payment history) in a format agreed upon with investors.

Portfolio Operations

Sold/Transferred Workflow

When a portfolio is sold:

  1. Portfolio status changes to sold
  2. Loan assignments to the purchasing investor are recorded
  3. Sale details (price, date, buyer) are tracked
  4. Snapshot at time of sale preserved for reference

Financial Metrics

Metric Calculation
IRR XIRR across all cash flows (disbursements and payments)
MOIC Total collections / total disbursements
Weighted average rate Sum(rate × balance) / Sum(balance)

Metrics are available at portfolio level, program level, and vintage level.

See Also