A homeowner types their address. Within seconds, the platform knows their property, their estimated equity, their benefit eligibility, and the current rate environment. A conversation begins: not a form, not a questionnaire, not a lead capture. The system leads with intelligence. The borrower confirms, corrects, and explores. Minutes later, they understand exactly what is possible for their specific situation, what the tradeoffs are, and what the path forward looks like. No account required. No sales call. No steering. Just clarity.
The Clarity Engine is PreFi's AI-powered borrower intelligence platform. It serves homeowners who have been systematically failed by an industry built to extract leads rather than deliver understanding. It was built because David Kawata's father: a U.S. military veteran: was denied home loans repeatedly and still rents today. Not because he couldn't qualify. Because the system was never designed to help him find out.
In Alpha, the Clarity Engine delivers two stages: Consultation and Validation. Together, they take a borrower from anonymous curiosity to a verified, personalized recommendation with a clear path forward. Every architectural decision in this document serves that journey: and is made the first time correctly so the Digital Lending Highway (DLH) can be built on top of it without tearing it out.
A builder reading this document should be able to answer the question 'are we done?' without ambiguity. Five summary criteria define Alpha success. The complete set of 11 measurable Go/No-Go acceptance criteria: each with a specific target and measurement method: is in Section 12. All 11 must pass before Alpha launch. No partial credit.
The Clarity Engine is designed as a six-stage platform. Alpha builds Stages 1 (Consultation) and 2 (Validation). Stages 3-6 are governed by the DLH PRD.
The stage boundary is a conversation, not a wall. Account creation at Step 8 links back to the anonymous Consultation session automatically: zero re-entry of data already captured is a build requirement, not a UX preference.
The Magical Moment occurs within Consultation at beat 6: between Explore and Summary. This map is the single reference for where each stage begins, what it contains, and where it hands off.
The Magical Moment is the most important single beat in the product. It is designed before it is built. The Design Team (Everett Co + Charlie Gann + BIX UI/UX) will deliver the rendering spec: trigger animation, analogy card design, and reduced-motion fallback: as a Discovery deliverable before BIX Sprint 1 begins.
Every stage is API-first from Sprint 1. No stage is coupled to any UI layer. The Purlend consumer experience, embedded partner widgets, and MCP tool invocations are all consumers of the same APIs. This is enforced in the repository structure from day one: no exceptions for Alpha convenience.
Future stages are not built in Alpha. But they impose specific output requirements on Consultation and Validation: outputs that must be produced correctly in Alpha or require a service rebuild before future stages can launch.
When multiple implementation approaches are possible, and the PRD does not explicitly cover the choice, the correct approach is the one that best aligns with these principles. These are not aspirational statements. They are decision filters.
Principle 1: The system always knows more than it asks.
The system retrieves before it requests. Wherever possible, context is gathered through permissioned data retrieval and inference before asking the borrower to provide information manually. Questions feel like confirmation or refinement, not interrogation. If the system is asking for data it could have already retrieved, that is a gap in the enrichment pipeline: not a conversation design choice.
Principle 2: Complexity is the system's problem, not the borrower's.
Mortgage logic is complex. Borrower experiences are not. The system handles eligibility rules, program logic, scenario modeling, and financial calculations. The borrower experiences clarity and forward progress. The product simplifies the decision without hiding the truth.
Principle 3: Every exit is a door, not a wall.
Borrowers never encounter a dead end. Anonymous users explore without creating an account: if they choose not to, their data is intentionally forgotten. If a borrower creates an account, the system remembers their progress exactly where they left it. Every stopping point is a pause in progress, not the end of the journey. Every exit has a specific, personalized, low-friction next step: not a generic call to action.
Principle 4: Math is the proof. Meaning is the message.
Borrowers care about what a financial decision means for their lives. Scenario presentation leads with meaning: monthly breathing room, financial flexibility, life outcomes: not calculations. The calculations exist as proof behind the message, always visible and transparent for borrowers who want them. '$247 less per month' is math. '$247 less per month means you stop choosing between the car payment and the kids' activities' is the meaning. The Storyboard component renders meaning first, math second, always.
Principle 5: The system remembers context so the borrower never starts from zero.
Mortgage decisions unfold over days or weeks. When borrowers return, the experience is a continuation, not a restart. The system remembers goals, prior exploration, and scenarios reviewed. For near-miss borrowers specifically: the system remembers not just their progress but their precise gap, and leads with what changed since they left.
Principle 6: Empathy and dignity guide every interaction.
Financial decisions around housing involve stress, uncertainty, and vulnerability. The system never creates shame, embarrassment, pressure, or unnecessary confusion. The Clarity Engine is a calm, knowledgeable advisor whose goal is to help borrowers understand their options: not judge their financial situation. When a scenario does not work, the system presents alternative paths rather than framing the outcome as rejection. Borrowers leave every interaction feeling informed, respected, and in control. This is the principle that governs how the system serves the veteran, the first-generation homeowner, and every borrower the mortgage industry was not built for.
The Clarity Engine contains a specific moment where confusion becomes understanding. This moment occurs when the system translates complex financial mechanics into a realization that the borrower immediately grasps. The purpose is not to explain mortgage math. It is to help the borrower recognize what their options mean for their life. When it works correctly, the borrower experiences a shift from uncertainty to clarity and continues exploring with confidence. This moment must be designed before it is built. The Storyboard component owns its rendering. The Advisor component owns its detection. The animation must respect prefers-reduced-motion.
Every interaction communicates calm confidence. The system is thoughtful, steady, and intelligent. Borrowers are never rushed, pressured, or overwhelmed. The experience is a conversation with a knowledgeable guide helping them think clearly. Warm without being casual. Simple without being sparse. Trustworthy without being formal. This is the emotional target the EI layer enforces across every stage, every archetype, every exit point.
The Oracle component classifies every borrower into one of five archetypes within the first three to five conversational exchanges. Archetypes are not fixed: a borrower can move between them within a session. Archetype shapes tone, pacing, and scenario framing. It does not change the underlying math or eligibility logic. The Oracle classification is recorded in the canonical ledger and carried through all stages and sessions.
The anonymous stage. No PII required. No account required. The borrower arrives with a feeling and leaves with a personalized recommendation: scenarios built on their specific property, benefit eligibility, and rate environment. This is the prescription delivered before verification. The system already knows more than it asks.
All three enrichment tracks (property data, benefit eligibility, rate environment) execute in parallel on address entry: before the conversation's first question. Design Principle 1 (the system always knows more than it asks) is implemented through this pipeline.
The ten-step sequence is a reference model: it defines every state the system must be capable of supporting, not a fixed execution order. The Magical Moment may fire earlier than Step 7 or not at all in a given session. Account creation may occur before Step 8. The system must support the full sequence; the borrower experience is fluid, not rigid.
The system supports all six refinance benefit types with full stacking logic and veteran overlays.
Defined trigger conditions, handoff architecture, and session data portability for human escalation.
The verification stage. The borrower has seen their recommendation. Now they connect real data: soft credit pull, income, assets: to confirm, refine, or adjust what Consultation showed them with their actual numbers. The output is a verified qualification state. Not a denial. A state: Qualified, Near-Miss, or Pathway Required: each with a specific next step and a clear path forward.
Consent Service governs each data source independently. Qualification Engine routes VA-eligible borrowers to residual income logic. Near-miss schema writes regardless of qualification state.
From consent through qualification to ledger write.
Every verification type has three paths. The happy path is automated. The fallback is manual upload. The final fallback is self-reported with explicit disclosure. No borrower hits a dead end because an automated verification fails. Self-employed borrowers: approximately 15% of the market: must be fully supported without routing to manual escalation.
The qualification engine implements qualification logic for three programs in Alpha. All logic references Fannie Mae Selling Guide December 2025 edition for conventional, VA Lenders Handbook for VA, and FHA Single Family Handbook 4000.1 for FHA.
A near-miss is not a soft no. It is the most precise yes in the system: the borrower who knows exactly what they need, and the system that knows exactly when they get there. Near-miss is the highest-fidelity entry point into Nurture and the first implementation of Always Approved. The near-miss schema is written at every Validation close regardless of qualification state.
Always Approved is a Digital Lending Highway design principle defined in the DLH PRD. The Clarity Engine implements it through the Validation stage gap analysis and near-miss schema. What the Clarity Engine must produce correctly in Alpha:
These nine decisions are specified as DLH standards: not Clarity Engine conveniences. Each one is a schema design or service boundary decision made in Discovery D3. None of them add sprint scope to the Alpha build. All of them are irreversible if made incorrectly: the cost of getting them wrong is a production line teardown at the moment Purlend is launching Production Line 2, onboarding its first partner, or activating Always Approved.
The Conversation Engine never calls platform services directly. All proposals pass through the Orchestration Layer. This separation prevents the conversation layer from bypassing consent enforcement, data classification, or business logic.
Full multi-tenant architecture is deferred to the DLH PRD. One constraint is non-negotiable in Alpha: Every table in the database that contains borrower or session data must include a tenant_id field from day one. Default value is the PreFi tenant identifier. No multi-tenant logic is built in Alpha. One field. One schema decision. The cost is thirty minutes in D3. The benefit is that the first partner integration does not require a database migration across every table that touches borrower data at the moment Purlend's first partner is ready to go live.
IP separation enforced by CI from Sprint 1.
Every AI-generated response containing financial figures or scenario comparisons is scored for neutrality by the control plane before delivery to the borrower. Responses scoring below 85 are flagged and a revised response is triggered automatically. Neutrality scores are logged in the canonical ledger as hash-anchored compliance events. Neutrality score distribution is a reportable metric in PostHog: monitored weekly.
ATTOM Data, Array, Truv, Plaid, FRED API, VA API, DPA Resource integrations.
All eleven criteria must pass. No partial credit. No launch with open items on this list.
Open items with BLOCKER status must be resolved before the affected deliverable begins. Open items with DEPENDENCY status must be resolved before Alpha launch. Owner is accountable for resolution and must update status weekly.
This field map defines what the Clarity Engine captures and when. BIX must produce a complete field-by-field MISMO 3.6 mapping in Discovery D3. Fields marked FUTURE are not captured in Alpha but the schema must not foreclose their addition.
Full specifications for Stages 3 through 6 are governed by the DLH PRD. The following light specifications define what each future stage requires from the Alpha build: constraints that must be respected in Alpha to avoid a production line rebuild when future stages launch.