Servicer Domain¶

The Servicer domain provides analytics for loan servicing operations: payment processing, accrual calculations, delinquency tracking, reconciliation, and regulatory reporting. While CalcBridge started as a CLO analytics platform, loan servicing represents a distinct segment with different compliance requirements, risk models, and operational workflows.

What Is Loan Servicing?¶

When a bank or financial institution originates a loan, someone has to handle the day-to-day administration: collecting monthly payments, tracking which borrowers are late, processing modifications when borrowers hit hardship, and reporting everything back to the entity that owns the loan. That role is the servicer.

Think of it as the difference between a landlord and a property manager. The landlord owns the asset and cares about returns. The property manager handles operations -- collecting rent, coordinating maintenance, managing tenant communications. The landlord might never interact with tenants directly; the property manager handles everything.

In structured finance, this distinction is critical. The loans inside a CLO are almost always serviced by a third-party servicer who has no economic interest in the portfolio's credit performance. The CLO manager owns the risk. The servicer handles the mechanics.

CLO Manager vs Loan Servicer¶

Engineers building CalcBridge templates or features need to understand which segment they are serving. The operational models are fundamentally different:

The Connection¶

Loans inside a CLO are typically serviced by a third-party servicer. The CLO manager selects the servicer, monitors their performance, and can replace them if servicing quality degrades. This means:

• A single loan can appear in both a CLO manager's portfolio and a servicer's operational data
• The CLO manager cares about the loan's credit metrics (rating, spread, maturity)
• The servicer cares about the loan's operational status (payment history, escrow balance, modification status)
• CalcBridge needs to serve both perspectives, but with different feature sets

flowchart LR
    subgraph Servicer["Servicer (Operations)"]
        S1["Collect Payments"]
        S2["Track Delinquencies"]
        S3["Process Modifications"]
        S4["Remit to Owner"]
    end

    subgraph Manager["CLO Manager (Investment)"]
        M1["Monitor Credit Quality"]
        M2["Run Compliance Tests"]
        M3["Execute Trades"]
        M4["Report to Investors"]
    end

    S4 -->|"Cash flows + reporting"| M1

    style Servicer fill:#DCFCE7,stroke:#22C55E
    style Manager fill:#DBEAFE,stroke:#3B82F6

Feature Mapping¶

CalcBridge features serve both segments, but the use cases are different. Engineers should understand which context applies when building or extending features:

FARF: CalcBridge's Servicing Implementation¶

What Is FARF?¶

The Federal Agency Receivables Fund (FARF) is CalcBridge's first -- and currently only -- production servicing client. FARF manages receivables from US federal government agencies. These are not leveraged loans in the traditional sense; they are government payment obligations with distinct characteristics:

• Counterparty risk: US government agencies (not corporate borrowers)
• Payment patterns: Government fiscal cycles, continuing resolutions, budget sequestration
• Regulatory environment: Federal procurement regulations rather than consumer lending law
• Collateral type: Government receivables, not real estate or corporate assets

FARF Architecture¶

FARF operates as a standalone Flask application (fidera/farf/) with its own database, models, and import pipeline. It follows the Model-Importer-Calculation Service pattern used throughout CalcBridge:

flowchart TD
    subgraph Input["Data Sources"]
        EXCEL["Excel Workbooks\n(Operational Snapshots)"]
        GENEVA["Geneva XML\n(Portfolio Accounting)"]
        JPM["JPM Feeds\n(Cash Reconciliation)"]
    end

    subgraph Pipeline["FARF Processing Pipeline"]
        IMP["Importers\n(Excel parsing + validation)"]
        CALC["Calculation Services\n(Vectorized pandas/numpy)"]
        MODEL["Pydantic Models\n(Validation + typing)"]
        DB["PostgreSQL + JSONB\n(Storage)"]
    end

    subgraph Output["Applications"]
        WEB["Flask Webapp\n(Domains: buy, sell, define,\nnomad, vrs, twf, twp)"]
        REPORTS["Regulatory Reports"]
        RECON["Reconciliation Reports"]
    end

    EXCEL --> IMP
    GENEVA --> WEB
    JPM --> RECON
    IMP --> CALC
    CALC --> MODEL
    MODEL --> DB
    DB --> WEB
    DB --> REPORTS

    style Pipeline fill:#F0FDF4,stroke:#22C55E

Key FARF Components¶

Third-Party Integrations¶

Cross-Sheet Calculation Pipeline¶

The FARF calculation pipeline processes multiple interconnected Excel sheets. Import order matters because later sheets depend on data from earlier ones.

Import Order¶

flowchart LR
    KD["1. Key Data\n(Agency Lookups)"] --> PME["2. PME\n(Private Market Equiv.)"]
    PME --> ABC["3. ABC\n(Primary Portfolio)"]
    PME --> ATLYS["4. Atlys\n(Secondary Portfolio)"]

    style KD fill:#FEF3C7,stroke:#F59E0B
    style PME fill:#DBEAFE,stroke:#3B82F6
    style ABC fill:#DCFCE7,stroke:#22C55E
    style ATLYS fill:#DCFCE7,stroke:#22C55E

Calculation Services¶

Each sheet has a dedicated calculation service that implements the CA-CI derived columns using vectorized pandas/numpy operations:

Calculated Columns (CA-CI)¶

Servicer sheets include derived columns that are excluded during Excel import and computed by CalcBridge using vectorized operations. This mirrors how Excel users see calculated columns in their workbooks, but with significant performance improvements.

ABC Columns¶

Atlys Columns¶

Vectorized Calculation Example¶

All calculated columns use vectorized pandas/numpy operations for performance. Here is the pattern used for conditional calculations:

import numpy as np
import pandas as pd

# Conditional: Realised Days (CB)
# If Senior Principal Balance <= 0, use Days Open; otherwise 0
df['realised_days'] = np.where(
    df['senior_principal_balance'] <= 0,
    df['days_open'],
    0
)

# Weighted aggregation: Weighted Realised Days (CC)
total_paid_loans = df.loc[
    df['senior_principal_balance'] <= 0, 'senior_loan'
].sum()
df['weighted_realised_days'] = np.where(
    df['senior_principal_balance'] <= 0,
    df['senior_loan'] / total_paid_loans * df['days_open'],
    0
)

# Cross-sheet lookup: P&L (CG)
pme_lookup = dict(zip(pme_df['y_cusip_a'], pme_df['pnl']))
df['pnl'] = df['y_cusip_a'].map(pme_lookup)

# Ratio with division-by-zero handling: CF
df['outstanding_to_collateral'] = np.where(
    df['collateral_value'] != 0,
    df['senior_outstanding'] / df['collateral_value'],
    np.nan
)

Y-Cusip-A: The Universal Key¶

Y-Cusip-A serves as the unique identifier across all FARF sheets. It is always located in column BW for ABC, Atlys, and PME sheets. This consistency simplifies cross-sheet lookups and database joins.

Alias Profiles¶

CalcBridge includes 14 servicer alias profiles for normalizing data from different servicing systems and regulatory templates:

Profile Structure¶

Servicer profiles organize aliases by section, reflecting the multi-sheet structure of servicing workbooks:

{
  "profile": "profile_name",
  "sheet_name_hints": {
    "key_data": ["Key Data", "Summary"],
    "risk_restrictions": ["Risk", "Restrictions"],
    "capital": ["Capital", "Investors"]
  },
  "section_aliases": {
    "key_data": {
      "snapshot": ["field aliases..."],
      "borrower": ["field aliases..."],
      "portfolio_composition": ["field aliases..."]
    },
    "risk_restrictions": {
      "borrower": ["field aliases..."],
      "region": ["field aliases..."]
    }
  }
}

Webapp Domains¶

The FARF webapp exposes servicing operations through a domain-driven Flask architecture:

Building Servicing Features¶

What Exists Today¶

• FARF production pipeline with complete Excel-to-database flow
• 14 alias profiles covering BoE, RBA, ECB, and custom templates
• Vectorized calculation services for CA-CI columns
• Cross-sheet dependency management with caching
• Geneva XML and JPM integration adapters

What Does Not Exist Yet¶

• Generalized servicing template library (FARF is bespoke)
• Servicing compliance test suite in CalcBridge core (see Servicing Tests for the framework)
• Payment waterfall engine for general loan servicing
• Borrower communication tracking
• Escrow calculation engine
• Loss mitigation workflow

Related Documentation¶

• Alias Profiles - How alias profiles work across domains
• CLO Domain - CLO-specific analytics (contrast with servicing)
• Servicing Compliance Tests - Compliance test framework for servicing operations
• Regulatory Landscape - Regulations driving both CLO and servicing features
• Compliance Testing - CLO compliance testing (for comparison)