Sooner finance schema working doc

Structured Payload Direction

Field names in this catalog are proposed backend-facing payload paths, not a mirror of the current input components. The submitted payload should prefer statuses and repeatable child arrays where the concept has more than two states or can occur more than once.

{
  "application": {
    "mortgageSearchStatus": "searching"
  },
  "propertyPreference": {
    "propertySearchStatus": "identified",
    "targetAmount": 2500000,
    "currency": "AED"
  },
  "parties": [
    {
      "roles": ["primary_applicant"],
      "person": {
        "firstName": "Amina",
        "middleName": null,
        "lastName": "Khan",
        "legalFullName": "Amina Khan"
      },
      "contactMethods": [
        { "type": "email", "value": "amina@example.com" },
        { "type": "phone", "value": "+971..." }
      ],
      "employment": [],
      "incomeSources": [],
      "liabilities": []
    }
  ]
}

Party Modeling Note

co_applicant is not a separate table and should not become a prefixed field family. It is a role value in ApplicationPartyRole for an ApplicationParty. Each party points to a Person and owns the application-specific facts collected for that participant: employment, income, liabilities, documents, consents, and relationship to the primary applicant. This is the reason the payload uses parties[] instead of primary_* and co_applicant_* columns.

Derived And Display-Only Values

These values appear in Sooner Forms Flow but are not borrower-submitted facts. Persist them only when Sooner needs an audit trail, quote snapshot, decision snapshot, analytics event, or short-term UI trace. If they are only display/supporting values, store them under the relevant owner record's metadata JSON column with lower snake case keys.

Schema Comment Seeds

These are draft comments that can later move near Prisma models once names settle.

• Application: “A finance journey/case file for one or more application parties. A person may have multiple applications over time; nullified or restarted journeys create new records.”
• ApplicationParty: “A person participating in an application. Keep participation separate from legal/workflow capacity and party-to-party relationship.”
• ApplicationPartyRole: “Repeatable role/capacity for an application party, such as borrower, guarantor, occupier, representative, broker adviser, or lender contact.”
• RelatedContact: “A contact-only person or institution that may support an application without becoming an application party.”
• ContactMethod: “Reusable email, phone, or WhatsApp method that can belong to a person, institution, related contact, or application context.”
• Address: “Structured postal or physical address. Link it to people, institutions, properties, or application-specific facts through explicit owner rows.”
• LenderSubmission: “One lender-specific path for a set of requested terms. DIP/AIP, underwriting, decisions, conditions, and offers hang from this path.”
• ApplicationPropertyPreference: “A buyer’s property-search intent, including target amount, location choices, property type choices, bedroom/bathroom count choices, purchase timeline, intended use, search status, and optional specific-property intake detail.”
• Employment: “Repeatable employment or business profile for an application party. Do not flatten co-applicant employment into prefixed canonical columns.”
• IncomeSource: “Repeatable income component with amount, currency, cadence, and verification state. Use this for salary, commission, self-employment income, and future market-specific income types.”
• CreditCheck: “Soft or hard credit search event. Provider-specific reports, scores, and tradelines hang from the returned report.”
• Liability: “Repeatable obligation used for affordability. AECB is one provider of verified credit data, not the model name.”
• HousingExpense: “Repeatable housing cost such as rent. Keep it separate from debt liabilities.”
• ApplicationCostEstimate: “Calculated quote/cost snapshot shown to the applicant. Do not treat displayed costs as submitted capture fields.”
• FeeQuote: “Displayed fee-tier snapshot derived from selected services and pricing rules.”
• Document: “Generic uploaded or generated file. Country-specific IDs are document types; evidence meaning lives in typed document links and requirements.”

Prompt Text

Candidate text to add to agent instructions.

## Finance Domain Naming Standards

Sooner is not inventing a new consumer-finance data model. When naming Prisma models, fields, enums, API resources, events, and workflow concepts, prefer established lending and mortgage terminology before creating local product names.

Use current industry vocabulary from mortgage and consumer-finance systems, including MISMO-style concepts where relevant: application, party, role/capacity, borrower/applicant, income, employment, asset, liability, credit check, credit report, property preference, document, requirement, lender submission, decision, offer, case, and workflow.

Use UK-facing language where the product or user experience is UK-aligned: mortgage application, applicant, joint applicant, affordability assessment, credit reference agency, Decision in Principle, Agreement in Principle, mortgage offer, solicitor, conveyancer, and completion.

Use the casing that matches the artifact being edited. In database-facing schema docs, describe tables, columns, and stored enum values in lower_snake_case. In Prisma schema code, use PascalCase model names and camelCase field names only when those are mapped deliberately to lower_snake_case database names. Frontend form state and API JSON may use nested camelCase payload paths, such as propertyPreference.propertySearchStatus, parties[].person.firstName, parties[].incomeSources[].amount, or parties[].documents[].documentType.

Keep schema names market-portable. Do not hard-code UAE, AED, AECB, Emirates ID, visa, or any other country/provider-specific concept into generic table or field names unless the model is explicitly market-specific reference data. Store these as values such as countryCode, currency, documentType, localDocumentType, provider, institution, or market.

Prefer bounded-context clarity over long prefixes. Inside a finance schema or finance module, Application is clear. Use MortgageApplication only when the domain is explicitly mortgage-only. Use LoanApplication only when the product is legally and operationally a loan application. Use FinanceApplication only when the model lives in a broad core namespace and Application would be ambiguous.

Model relationships instead of flattening roles into columns. A person can have multiple applications. An application can have multiple parties. Use ApplicationParty for participation, ApplicationPartyRole for legal/workflow capacity, and ApplicationPartyRelationship for relationships between parties. Do not overload one role field with borrower status, spouse relationship, representative-for semantics, and workflow role.

Treat form branch flags as intake controls, not durable schema facts. A field such as hasCoApplicant should create or omit an ApplicationParty and assign co_applicant through ApplicationPartyRole. A field such as hasSpecificProperty should set ApplicationPropertyPreference.propertySearchStatus and may store typed intake detail in metadata.specific_property when the form captures it.

Use metadata JSON deliberately. Make the metadata destination explicit as metadata JSON on the owning record, with snake_case JSON keys. Add metadata only to the owner record that gives the data meaning, such as application.metadata for application-wide form/UI state, application_property_preference.metadata for specific-property intake detail, fee_quote.metadata for supporting displayed quote detail, or document_review.metadata for provider/tool payload fragments. Persist metadata object keys in lower_snake_case. Do not hide queryable, repeatable, auditable, or workflow-relevant finance facts in metadata.

Separate identity from contact information. Use ContactMethod for reusable email, phone, and WhatsApp methods. Use Address for structured postal or physical addresses. Use RelatedContact and ApplicationRelatedContact for partner, emergency, employer, adviser, lender, solicitor, conveyancer, or other contacts that matter to an application but are not necessarily canonical platform people or application parties.

Use LenderSubmission as the lender-specific path inside an application. Decision in Principle, Agreement in Principle, full underwriting, lender conditions, credit decisions, and mortgage offers should hang from the lender submission rather than being flattened into one application status.

Model repeatable financial facts as child records. Employment, income sources, assets, liabilities, housing expenses, funding sources, credit checks, credit reports, decisions, and offers should not be collapsed into one application row or duplicated through primary/co-applicant-prefixed canonical columns.

Keep housing expenses separate from debt liabilities. Rent belongs in HousingExpense, while mortgages, personal loans, vehicle loans, credit cards, overdrafts, leases, support obligations, and other debts belong in Liability.

Keep property modeling simple. Use ApplicationPropertyPreference for target amount, selected locations, property type choices, bedroom/bathroom count choices, purchase timeline, intended use, and property-search status. Use Property as a lightweight property/location anchor, PropertyListing as the sourced option/listing with unit-like facts merged into the listing, and ApplicationPropertyMatch for applicant-specific candidate workflow. Do not add PropertyUnit, valuation, ownership, security-property, lender-property, or recommendation-engine tables in this pass unless a concrete product flow requires them.

Do not turn display-only outputs into submitted fields. Cost breakdowns, Sooner reveal events, fee tiers, SCS scores, decisions, and gate failures are derived outputs. Persist them through ApplicationCostEstimate, FeeQuote, AffordabilityAssessment, DecisionInPrinciple, or CreditDecision only when audit history or customer-visible quote history is required.

Keep Person as stable identity. A person can become a platform user, an applicant through an application party, and a customer after approval/completion. Do not use Lead, Buyer, or Customer as the canonical identity object unless there is a deliberate lifecycle or CRM boundary.

Treat Lead as CRM intake only, not the core finance aggregate. If active workflow state is needed, prefer concrete typed links to Application, MortgageCase, LenderSubmission, ApplicationParty, Document, Conversation, or Institution. Use polymorphic subjectType/subjectId only for immutable audit, webhook, or event payloads where database-level FK enforcement is not required.

Use documents as typed evidence. Do not create permanent columns for one market's document tiles, such as emiratesIdFront, visaPage, or aecbReport. Use Document for the file, DocumentLink for typed evidence targets, DocumentRequirement for evidence requests, DocumentRequirementDocument for satisfaction, and DocumentReview/DocumentExtraction for review and extraction state.

Separate typed values from document evidence. A trade license number is an Employment snapshot value or InstitutionIdentifier. A trade license PDF is Document evidence linked to the employment/business or identifier. Apply the same rule to credit reports: AECB is the provider, not the model name.

Do not introduce property ownership, valuation, title, security-property, lender-property, or recommendation-engine models from Gabriel's current forms. For sourced property options or migrated listing candidates, keep the model simple: Property, PropertyListing, and ApplicationPropertyMatch. For intake-only typed detail, use metadata on ApplicationPropertyPreference with lower_snake_case keys.

Separate institution from IAM. Use Institution for real-world finance ecosystem entities such as lenders, employers, brokers, solicitors, conveyancers, valuers, insurers, government agencies, and credit reference agencies. Use PlatformAccount for the Sooner product account that links platform access to a Person. Use AuthorizationAssignment and BundleAssignment for tenant-scoped Sooner-IAM access. Use ImportedRecordLink only for lineage back to migrated or imported source rows.

Keep the first-pass identity model simple. Use Person for the stable human and ApplicationParty for that human's participation in one application. Store submitted identity facts in IdentityProfile, Nationality, Residency, and TaxResidency records scoped by applicationPartyId. Do not add person-level identity profile tables until Sooner needs cross-application prefill or long-lived verification profiles. Do not use scalar nationalityCountryCode or residencyCountryCode columns on Person.

Separate lifecycle records. Preliminary eligibility, affordability assessment, credit decision, underwriting result, formal mortgage offer, completion, cancellation, withdrawal, expiry, and nullification should not all be overloaded into one generic status field.

Scope rejection feedback to the rejected object. Offer rejection reasons belong to the MortgageOffer or LenderSubmission response. Credit or document rejection reasons belong to CreditDecision or DocumentReview. Do not attach generic rejectionReason fields to Person or Application without a clear subject.

Use lower_snake_case stored enum values. Keep enum values short and context-aware, such as in_review, co_applicant, credit_report, decision_in_principle, mortgage_offer, withdrawn, nullified, and expired.

Before adding or renaming a finance-domain model or field, check whether the same concept already has a standard lending, mortgage, MISMO, FCA, lender, or credit-reporting name. If there is uncertainty, record the naming question in the working schema notes instead of inventing a local abstraction.