Data Model Overview

Foundation is the system of record for the platform, and its data model is organized around a simple spine: a person owes one or more debts, each debt is owed to a creditor, and money moving against those debts is tracked as payments. Everything else — contact details, incoming mail, documents — hangs off that spine.

This page is the map of the core entities. It’s deliberately a starting point: Foundation has 200+ models, so this covers the load-bearing ones, not every table.

Entity relationships

erDiagram
    PERSON ||--o{ DEBT : "owes"
    PERSON ||--o{ PHONE_NUMBER : "has"
    PERSON ||--o{ EMAIL_ADDRESS : "has"
    PERSON ||--o{ PHYSICAL_ADDRESS : "has"
    PERSON ||--o{ PAYMENT_HISTORY : "makes"
    PERSON ||--o{ BANK_ACCOUNT : "has"
    PERSON ||--o{ CREDIT_CARD : "has"
    PERSON ||--o{ INBOUND_LETTER : "receives"

    CREDITOR ||--o{ DEBT : "is owed"
    CREDITOR ||--o{ CREDITOR_CONTACT : "reached via"
    DEBT_TYPE ||--o{ DEBT : "classifies"
    DEBT ||--o{ INBOUND_LETTER : "concerns"

    PERSON {
        int id PK
        string first_name
        string last_name
        string portfolio "RESPRO, MLG, MLG-BK, OTHER"
        string language "English, Spanish"
    }
    DEBT {
        int id PK
        int person_id FK
        int creditor_id FK
        int debt_type_id FK
        string status "see Debt Status Codes"
        string whos_debt
        decimal original_amount
        decimal current_balance
        date opened_date
        boolean has_summons
    }
    CREDITOR {
        int id PK
        string name
    }
    DEBT_TYPE {
        int id PK
        string name "credit card, auto, medical, ..."
    }
    PAYMENT_HISTORY {
        int id PK
        int person_id FK
        decimal amount
        string method "ACH, CC"
        string status "Success, Returned, Settled, ..."
    }
    INBOUND_LETTER {
        int id PK
        int person_id FK
        string file_type
        string status "OCR / classification / review"
    }

The entities

• Person — the consumer. Assigned to a portfolio and a preferred language. Contact details (phone, email, physical address) live in their own tables so a person can have several of each, one marked primary.
• Debt — a single obligation. Points at the person who owes it, the creditor it’s owed to, and a debt type. Carries the amounts, the status, the whos_debt relationship, and — when litigation is involved — summons and court-date fields.
• Creditor — an organization owed money: an original creditor, a debt buyer, or a collection agency. Contact points live in CreditorContact.
• Debt Type — the category of debt (credit card, auto, medical, and so on).
• Payment History — the audit trail of money moving, by ACH or card, with a processor status on each row.
• Bank Account / Credit Card — stored payment methods. Card data is tokenized through VGS rather than stored directly (see Integrations); several of these records originate in Forth.
• Inbound Letter — a scanned piece of correspondence tied to a person (and often a specific debt), moving through the inbound-letter pipeline.

Representative, not exhaustive

Field lists above are the load-bearing columns, not the full schema. As we document more of the model, extend this diagram or split it — a person-and-debts diagram and a payments diagram will read more clearly than one giant chart.

---

Source: foundation/people/models.py, foundation/debts/models.py, foundation/payments/models.py, foundation/inbound/models.py.