System Architecture + Engineering Blueprint Component Specifications • Data Flow • API Boundaries • Database Schema • Build Sequence BIX Technology Corp | Purlend / PreFi, Inc. | CONFIDENTIAL | Architecture v1.0
This document is the BIX engineering blueprint for the Clarity Engine. It defines the system architecture, all component specifications, the end-to-end data flow, API boundaries, database entities, and build sequencing. Engineers should read this document alongside the Master PRD (optimization logic and decision tree) and the Worked Examples (mortgage math derivations).
The Clarity Engine is the decisioning and optimization brain inside Purlend. It is not a rules engine. It is a mortgage outcome optimization engine.
Build the Clarity Engine as a modular outcome-optimization system that first diagnoses the borrower’s constraints, then searches program, incentive, and structural combinations to produce the best explainable financing path.
The Clarity Engine is organized into five architectural layers. Data flows top-to-bottom through the layers, with the Governance layer receiving writes from every component.
Borrower Inputs → Property Inputs → Market / Program Data → Incentive / Grant Data
Borrower Profile Service → Property Intelligence Service → Program & Pricing Library → Incentive Intelligence Service
Financial Twin Builder → Baseline Eligibility Engine → Constraint Detection → Optimization Move Library → Scenario Generation → Scenario Scoring & Ranking → Recommendation Engine
Explanation Layer → Nova AI Loan Officer → Advisor / Ops Dashboard
Audit & Compliance Log → Rules Versioning → Model Monitoring
Data flow summary: Intake feeds Normalization. Normalization feeds Decision Core. Decision Core feeds Experience. All layers write to Governance.
Key Architectural Properties
Detailed specification for each of the fourteen system components. Each component is defined by its inputs, responsibilities, and key outputs.
A. Borrower Profile Service A Borrower Profile Service
B. Property Intelligence Service B Property Intelligence Service
C. Program & Pricing Library C Program & Pricing Library
D. Incentive Intelligence Service D Incentive Intelligence Service
E. Financial Twin Builder E Financial Twin Builder
F. Baseline Eligibility Engine F Baseline Eligibility Engine
G. Constraint Detection Engine G Constraint Detection Engine
// Example Constraint Detection Output
{
"primary_constraint": "cash_to_close",
"secondary_constraints": [
{ "type": "credit_tier_pricing", "severity": "medium" },
{ "type": "dti_sensitivity", "severity": "low" }
],
"primary_severity": "high",
"optimization_paths": ["B_cash_to_close", "D_credit", "A_dti"],
"estimated_gap": {
"cash_shortfall_usd": 14500,
"score_to_next_tier": 22,
"dti_reduction_needed": 0.031
}}
H. Optimization Move Library H Optimization Move Library
// Example Move Object
{
"move_id": "payoff_revolving_under_30pct",
"category": "debt_optimization",
"domain": "credit_utilization",
"applies_when": ["revolving_utilization_gt_30pct", "borrower_has_liquid_assets"],
"expected_impacts": [
{ "dimension": "fico_score", "delta": "+20 to +40 pts", "confidence": "high" },
{ "dimension": "rate_tier", "delta": "may cross tier", "confidence": "medium" },
{ "dimension": "monthly_pmt", "delta": "-$45 to -$120", "confidence": "medium" }
],
"execution": {
"complexity": "low",
"borrower_cost": "calculated_per_balance",
"timeline": "immediate_to_45_days"
},
"compliance_notes": "Standard paydown. No disclosure required.",
"dependencies": []
}I. Scenario Generation Engine I Scenario Generation Engine
// Example Scenario Object
{
"scenario_id": "scen_0142",
"base_program": "FHA_3.5pct",
"moves_applied": ["payoff_cc_card1", "apply_county_dpa_grant", "seller_cc_credit"],
"incentives": ["county_dpa_9500", "cra_lender_credit_5000"],
"outcomes": {
"loan_amount": 398500,
"purchase_price": 450000,
"down_payment": 15750,
"cash_to_close": 6250,
"monthly_piti": 2614,
"back_end_dti": 0.381,
"ltv": 0.885,
"total_interest_30yr": 441820,
"approval_confidence": "high"
},
"delta_vs_baseline": {
"purchase_price_delta": +45000,
"cash_to_close_delta": -14250,
"monthly_pmt_delta": -214
}}
J. Scenario Scoring & Ranking Engine J Scenario Scoring & Ranking Engine
K. Recommendation Engine K Recommendation Engine
// Recommendation Output Object
{
"current_affordability": 485000,
"optimized_affordability": 565000,
"safe_option": {
"scenario_id": "scen_0031",
"label": "FHA Standard",
"confidence": "high",
"monthly_pmt": 2614,
"cash_to_close": 19800
},
"optimal_option": {
"scenario_id": "scen_0142",
"label": "FHA + County DPA + Seller Credit",
"confidence": "high",
"monthly_pmt": 2614,
"cash_to_close": 6250,
"key_moves": ["apply_county_dpa_9500", "seller_credit_5000"]
},
"transformational_option": {
"scenario_id": "scen_0287",
"label": "Conventional after credit optimization",
"confidence": "medium",
"monthly_pmt": 2489,
"cash_to_close": 8100,
"action_plan": [
{ "step": 1, "action": "Pay Chase card from $4200 to $1260", "timeline": "immediate", "projected_score_impact": "+28 pts" },
{ "step": 2, "action": "Dispute Equifax duplicate collection", "timeline": "5-7 business days", "projected_score_impact": "+12 pts" },
{ "step": 3, "action": "Re-run baseline eligibility at score 658", "timeline": "45 days", "expected_unlock": "Conventional pricing tier 2" }
]
}}
L. Explanation Layer The Explanation Layer is one of the most important components in the system. A borrower does not care about internal scoring matrices. They care whether the answer makes sense and what to do next.
L Explanation Layer
DTI exceeds 43% threshold Paying down about $2,800 across two accounts would put you in a stronger approval range FICO: 618 — below Conv. tier 3 minimum You’re 22 points from a pricing tier that saves you $87/month permanently LTV: 88.4% — PMI required at 0.65% At this loan structure, a small monthly insurance cost applies until you reach 20% equity Constraint: cash_to_close — shortfall $14,250 A local grant program covers $9,500. A seller credit covers the remaining gap. Transformational: probability medium This option requires two steps. If you complete them in 45 days, I’ll have your approval ready.
M. Nova — AI Loan Officer Nova is the conversational presentation layer. Nova consumes Explanation Layer output and presents it in borrower-facing dialogue. Nova never recreates the math — it only consumes structured outputs. This separation protects both accuracy and scalability.
Borrower Prompt Nova Response Pattern ‘How much can I afford?’ Current range + optimized range + two specific moves that close the gap + offer to show both paths ‘My payment is too high’ Diagnose source (price / rate / taxes / debt) + 2-3 specific payment reduction options with dollar amounts ‘I was told I don’t qualify’ Exact score / DTI gap + 90-day action plan + monitoring promise + pre-approval commitment at threshold crossing ‘I want to pull cash out’ Clarify purpose + compare refi vs. HELOC vs. hybrid + show economics of each + ask what matters more ‘I served in the military’ VA benefit activation: calculate exact savings vs. conventional, zero-down scenario, funding fee status, Certificate of Eligibility request ‘Should I buy now or wait?’ Model both scenarios: current qualification + 6-month action plan outcome + rate sensitivity + total cost comparison
N. Advisor / Ops Dashboard The internal interface for loan advisors, operations teams, and Purlend staff. This is how humans supervise, annotate, and improve the system.
Every recommendation must be traceable. The governance layer is not optional — it is a regulatory requirement, a fair lending requirement, and a trust requirement with every lender and investor partner.
O. Audit & Compliance Log Every system action is written to an immutable audit log. This log is the basis for fair lending review, HMDA reporting, regulatory examination, and debugging.
Audit Event Type Data Captured Borrower Intake Raw inputs, timestamps, source system, session ID Data Normalization Input-to-output mapping, flags applied, completeness score Baseline Eligibility Run Programs tested, outcomes per program, friction notes Constraint Detection Primary and secondary constraints, severity scores, routing decision Moves Applied Every move attempted, eligibility result, impact calculated Scenario Generation Total scenarios generated, discarded (with reason), retained Ranking Output All scores, weight vectors applied, final tier assignments Recommendation Served Full recommendation object, explanation text, Nova output Borrower Action Actions taken, milestone completions, re-qualification triggers Human Override Advisor annotation, manual change, override rationale
The audit log must support ECOA / Reg B adverse action explainability: every recommendation must be traceable to objective, non-discriminatory factors. The system must run disparate impact testing: if any optimization move or ranking rule produces disproportionate adverse outcomes for a protected class, that rule must be flagged for review. All protected class data (race, ethnicity, sex, national origin, marital status, age) must never enter the optimization or ranking logic. This is a P0 requirement for every component in the Decision Core and Experience Layer.
The complete sequence of data transformations from raw borrower input to Nova’s recommendation.
01
Borrower submits URLA Form 1003, credit authorization, and property target. Data arrives via Intake UI, CRM/POS, or API. Session ID assigned. Raw data written to Audit Log.
02
Borrower Profile Service parses and normalizes income, debt, asset, and credit data. Property Intelligence Service enriches property with AVM, census tract, and loan limit data. Incentive Intelligence Service queries DPA/grant database for applicable programs.
03
Financial Twin Builder combines normalized borrower and property objects into a single DealState. Calculates DTI, LTV, reserves, liquidity, and borrower objective weights. This canonical object is the basis for all downstream computation.
04
Baseline Eligibility Engine tests the DealState against all eligible programs simultaneously. Returns a scenario set with max loan, payment, cash to close, and friction notes for each program. Identifies the gap between baseline and borrower targets.
05
Constraint Detection Engine compares baseline outcomes against targets. Classifies primary and secondary blockers with severity scores. Routes the optimization search to the correct branches of the move library.
06
Optimization Move Library returns applicable transformation moves ordered by expected impact. Each move is validated against eligibility criteria, compliance rules, and borrower capacity to execute.
07
Scenario Generation Engine composes hundreds of candidate deal structures by combining programs + moves + incentives. Each combination is fully calculated. Invalid combinations are discarded. High-potential scenarios are retained.
08
Scenario Scoring Engine scores all retained scenarios against borrower objective weights. Confidence-adjusted composite scores determine the ranked output. Three tiers are populated: Safe, Optimal, Transformational.
09
Recommendation Engine selects the top scenario from each tier. Attaches labels, key moves, and action plans. Produces structured recommendation object.
10
Explanation Layer converts structured outputs into plain-language borrower communication. Translates system terms into borrower terms. Generates action plans in friendly step format.
11
Nova presents the recommendation conversationally. Answers borrower questions. Explains tradeoffs. Guides borrower toward action. Routes human handoff when appropriate.
12
Every step above writes to the Audit & Compliance Log. All inputs, decisions, and outputs are immutably logged for fair lending review, regulatory examination, and system debugging.
Clean service API boundaries allow independent development, testing, scaling, and replacement of each component. BIX should implement these as discrete services from the start.
Service API Methods Borrower Profile API createBorrowerProfile | updateBorrowerProfile | getBorrowerMetrics | validateProfileCompleteness | classifyBorrowerType Property Intelligence API enrichProperty | getPropertyEligibilityFlags | estimatePropertyCosts | getLoanLimitsByCounty | getCensusTractFlags Program Library API getEligiblePrograms | getProgramRules | getPricingAssumptions | getMIPMIRates | getVersionHistory Incentive API getApplicableIncentives | estimateIncentiveValue | getStackablePrograms | checkFundingAvailability Financial Twin API buildDealState | updateDealState | getAffordabilityMetrics | getObjectiveWeights Eligibility API runBaselineEligibility | getProgramFrictionNotes | getQualificationGap Constraint API detectConstraints | classifyBlocker | getSeverityScore | getOptimizationPathRouting Optimization API getCandidateMoves | applyMove | validateMoveEligibility | getMoveImpactEstimate | generateScenarioSet Ranking API rankScenarios | getWeightedScore | assignScenarioTier | getTradeoffMatrix Recommendation API getTopRecommendations | getKeyMoves | getActionPlan Explanation API explainRecommendation | explainTradeoffs | explainUnlockPlan | translateToPlainLanguage Audit API logEvent | getAuditTrail | exportForCompliance | runDisparateImpactCheck
Core data objects the system must model. This is the minimum viable entity set for the Clarity Engine. The full Data Dictionary (a separate document) will specify every field, type, and constraint.
Entity Key Fields Relationships Borrower id, name, SSN, DOB, marital_status, veteran_flag, first_time_buyer_flag, self_employed_flag Has many: IncomeSources, Liabilities, Assets. Belongs to: Deal CoBorrower id, borrower_id, relationship, income, liabilities Belongs to: Borrower Property id, address, county, census_tract, type, occupancy, value_estimate, taxes, insurance, hoa, unit_count Belongs to: Deal. Has many: PropertyFlags Deal id, borrower_id, property_id, intent_type, target_payment, target_cash_to_close, target_price, created_at, state Has many: Scenarios, AuditEvents. Belongs to: Borrower, Property IncomeSource id, borrower_id, type, amount, frequency, documentation_status, qualifying_amount, add_back_amount Belongs to: Borrower Liability id, borrower_id, type, balance, monthly_payment, remaining_term, exclude_from_dti_flag Belongs to: Borrower Asset id, borrower_id, type, value, liquid_flag, retirement_flag, vested_pct Belongs to: Borrower Program id, name, type, min_fico, max_ltv, max_dti, min_down_pmt, mi_required, version, effective_date Has many: ProgramRules. Referenced by: Scenario Incentive id, name, type, geography_scope, amount, forgivable_flag, income_limit, eligible_buyer_types, funding_status Referenced by: Scenario OptimizationMove id, name, category, applies_when, expected_impacts, complexity, compliance_notes, dependencies Referenced by: Scenario (moves_applied array) Scenario id, deal_id, base_program_id, moves_applied[], incentives[], outcomes{}, delta_vs_baseline{}, score, tier Belongs to: Deal. References: Program, Incentive, OptimizationMove Recommendation id, deal_id, safe_scenario_id, optimal_scenario_id, transformational_scenario_id, key_moves[], action_plan[], created_at Belongs to: Deal AuditEvent id, deal_id, event_type, component, inputs_snapshot, outputs_snapshot, timestamp, user_id Belongs to: Deal. Immutable.
These seven principles govern every architectural and implementation decision for the Clarity Engine.
P1
Do not hardcode logic into a monolith. Program rules, incentive rules, optimization moves, and scoring weights are separate modules. Each can be updated, replaced, or versioned independently. A rate change in Fannie Mae guidelines should require a rules update, not a code deploy.
P2
No black-box outputs. Every recommendation must trace from input to output with a complete rationale chain. The Explanation Layer exists specifically to enforce this. If an engineer cannot explain why the system recommended Scenario B over Scenario A, the system is not production-ready.
P3
Always show three states: where the borrower is now (baseline), what changed (moves applied), and why the recommended option is better (delta vs. baseline). This comparison structure is what makes the engine’s recommendations trustworthy and auditable.
P4
A scenario is built from interchangeable components: borrower assumptions + program assumptions + incentive assumptions + transformation moves. Any combination must be calculable. This composability is what allows the engine to search thousands of structures efficiently.
P5
Rates, guidelines, incentive programs, and ranking logic will change — sometimes weekly. Every rule must have an effective date and an expiration date. The system must be able to reproduce any recommendation made at any point in the past using the rules that were active at that time.
P6
Especially in Phase 1. The Advisor Dashboard exists for this reason. Every borrower interaction should be reviewable by a human. The system proposes; humans supervise. This is both a regulatory requirement and a trust-building strategy with lender partners.
P7
Nova consumes structured outputs from the Recommendation Engine. Nova does not recreate the math. Nova does not access the Program Library or the Scenario Engine directly. This separation means Nova can be improved, replaced, or swapped across channels (chat, voice, email) without touching the core decisioning logic.
Sequencing is everything. The MVP must deliver the core optimization loop end-to-end. Phase 2 expands coverage, intelligence, and borrower self-service capabilities.
MVP: The Minimum Viable Optimization Engine
A borrower inputs their profile. The engine outputs: (1) what they qualify for today, (2) the optimized scenario with the top 2-3 moves, and (3) the action plan to reach the transformational scenario. That loop, working end-to-end with full audit logging and fair lending compliance, is the MVP.
# Component / Feature Sprint Priority 1 Borrower Profile Service — all 8 income types, full Schedule C add-back Gear 1 (Wk 1-4) P0 2 Property Intelligence Service — address enrichment, loan limits, AVM hook Gear 1 (Wk 1-4) P0 3 Financial Twin Builder — DealState object, full DTI / LTV / reserves Gear 1 (Wk 1-4) P0 4 Baseline Eligibility Engine — VA, USDA, Conv, FHA, Non-QM parallel run Gear 1 (Wk 1-4) P0 5 Constraint Detection Engine — all 8 blocker types with routing Gear 2 (Wk 5-8) P0 6 Optimization Move Library — 20-30 highest-impact moves (debt, credit, income, asset) Gear 2 (Wk 5-8) P0 7 DPA / Incentive database — county-indexed, auto-match to borrower Gear 2 (Wk 5-8) P0 8 Scenario Generation Engine — composable framework, 50-500 scenarios Gear 2 (Wk 5-8) P0 9 Scenario Scoring & Ranking Engine — weighted objective scoring Gear 2 (Wk 5-8) P0 10 Recommendation Engine — Safe / Optimal / Transformational output Gear 3 (Wk 9-12) P0 11 Explanation Layer — plain-language translation for all top scenarios Gear 3 (Wk 9-12) P0 12 Nova — 5 core conversation paths integrated with recommendation output Gear 3 (Wk 9-12) P0 13 Audit & Compliance Log — immutable event logging for all components Gear 1 (Wk 1-4) P0 14 Fair Lending Disparate Impact Testing — baked into ranking and explanation Gear 2 (Wk 5-8) P0 15 Advisor / Ops Dashboard — borrower snapshot, top 3 recs, audit trail Gear 3 (Wk 9-12) P1
Phase 2: Expanded Intelligence # Component / Feature Phase Priority 16 Broader DPA / incentive coverage — 50+ counties, state HFA programs Phase 2 P0 17 Advanced ranking logic — learning from funded outcomes Phase 2 P0 18 Richer Nova conversations — voice, email, multi-turn memory Phase 2 P1 19 Borrower self-serve unlock plans — milestone tracking, automated alerts Phase 2 P0 20 HELOC / second lien comparisons — hybrid structure modeling Phase 2 P1 21
Phase 2 P0 22 Portfolio / exception workflow logic — manual underwrite path Phase 2 P1 23 Refinance opportunity monitor — automated rate, equity, score triggers Phase 2 P0 24 Secondary market data hooks — pricing feed, commitment tracking Phase 2 P2 25 MISMO 3.6 full integration — lender API data interchange Phase 2 P1
Most mortgage tech helps a lender process a file. The Clarity Engine helps a borrower achieve a better outcome. That is a very different product. Build it that way.
Document: Clarity Engine System Architecture v1.0 | Companion documents: Master PRD v1.0, Worked Examples v1.0, Data Dictionary (next) | CONFIDENTIAL — PreFi, Inc. / Purpose Technology, Inc. (d/b/a Purlend)