Borrower UI: Repo & Application Architecture

Signup, Application, & Portal

Borrower UI serves the entire borrower experience.

borrower-interactions-ui

Three route groups

Auth guard→src/routes/_auth.tsx

Signup

Pre-auth flow — no login required

Public

Routes→src/pre-auth/

Application Wizard

Satisfy-code-driven screens

Auth Required

Entry→src/routes/_auth.app.$fileId.tsx

Borrower Portal

Tasks, documents, and messages

Auth Required

Entry→src/routes/_auth.tasks.tsx

ℹ️

Public signup lives outside auth; the wizard and portal sit behind an auth guard that bridges through Cognito.

Domain Folders Own Their Slice

Each folder contains its UI, API layer, and tests.

Application Domains

Application

Wizard screens and satisfy-code resolution

Pre-Auth

Signup flow and provider config

Application→src/application/

Pre-Auth→src/pre-auth/

Portal Domains

Tasks

Task-type handlers and card UI

Documents

Document list and uploads

Messages

Threaded message view

Tasks→src/tasks/

Documents→src/documents/

Messages→src/messages/

Fields

Typed form components

Shared

API Layer

Per-domain endpoints and schemas

Shared

Routes

File-based route tree

Shared

Source Files

Fields→src/fields/

API Layer→src/lib/endpoints.ts

Routes→src/routes/

ℹ️

Each domain API file exports schemas, query keys, and mutations — one file per entity, no scattered endpoints.

Decisions Drive Completion, Not Screen Order

Satisfy codes determine completion — screens are always present, not conditionally rendered.

Decision Result

Satisfy codes from the backend

Flatten & Match

Map codes to screen definitions

Active Screens

Each screen knows its codes and completion

Resolution Components

Screen Definitions

Fixed order, always included

Hardcoded

Code Definitions

Each code maps to a screen and its fields

Source of Truth

Completion Check

All matched codes passed — or no codes at all

Per-Screen

💡

Field values come from the borrower's file data — not from the decision result itself.

Source Files

Schema→src/lib/decision.api.ts

Resolver→src/application/resolve-screens.ts

Screen Definitions→src/application/screen-definitions.ts

Code Definitions→src/application/satisfy-code-definitions.ts

Codes Map to Screens

Each satisfy code declares its screen and required fields.

Basic Info

Name, DOB, SSN, contact

Identity

Property

Address, type, county

Collateral

Loan Details

Purpose, amount, terms

Product

Employment

One code, many fields — income types vary

Complex

Co-Borrower

Mirrors borrower — most codes of any screen

Complex

Demographics

Consent and HMDA fields

Compliance

Liabilities & Assets

Acknowledgement flags — single code each

Simple

Offer

Hard credit consent — outside wizard resolution

Post-Wizard

ℹ️

The mapping is the single source of truth — one lookup function returns all codes for any screen.

Source Files

Basic Info→screens/basic-info-screen.tsx

Property→screens/property-screen.tsx

Loan Details→screens/loan-details-screen.tsx

Employment→screens/employment-screen.tsx

Co-Borrower→screens/coborrower-screen.tsx

Demographics→screens/demographics-screen.tsx

Liabilities→screens/liabilities-screen.tsx

Assets→screens/assets-screen.tsx

Offer→screens/offer-screen.tsx

Two Submit Patterns, One Interface

Every screen calls the same submit handler. The renderer decides how to persist.

Form Defaults

Pre-filled from the borrower's file data on load

Auto-Populate

Navigation

URL-driven, sequential — must complete screens in order

Accessibility Gate

Form → Update File

Basic Info, Property, Loan Details, Demographics

Single PATCH

Own Mutations → Skip PATCH

Employment, Co-Borrower, Liabilities, Assets

Entity APIs

Post-Submit Lifecycle

Invalidate Queries

Decision + file data refresh

Advance

Next incomplete screen

Source Files

Form Defaults→src/application/screens/form-defaults.ts

Navigation→src/application/use-screen-navigation.ts

Handler→src/application/stage-renderer.tsx

Endpoints→src/lib/endpoints.ts

The Renderer Decides What to Show

One component handles all three states — wizard screens, offer, and confirmation.

Wizard Screen

Progress indicator + form + navigation

Active Screen Found

Offer Screen

Pricing display + acceptance

Wizard Complete

Confirmation

Application submitted

Stage Passed

Wizard Screen Types

Simple Screens

Basic Info, Property, Loan Details, Demographics

Form Fields

Entity Screens

Employment, Co-Borrower, Liabilities, Assets

Repeatable Cards

ℹ️

Every screen receives the same props contract — codes, file data, completion status, and submit handler.

Source Files

Renderer→src/application/stage-renderer.tsx

Indicator→src/application/stage-indicator.tsx

Props→src/application/application.schema.ts

Offer→src/application/screens/offer-screen.tsx

Confirmation→src/application/screens/submitted-screen.tsx

Card→src/application/repeatable-card.tsx

Card List→src/application/repeatable-card-list.tsx

From Rigid Rules to Flexible Codes

Three phases, each further decoupling screens from the decision engine.

Legacy Workflows

Hardcoded screen flows — each workflow was a fixed sequence with no dynamic behavior.

Rule-Driven

1:1 model — each rule key maps to one field. Simple but rigid.

Satisfy-Codes Redesign

1:many model — one code maps to multiple fields. All screens always rendered; codes drive completion only.

Before

1 rule = 1 field

Screens conditionally rendered

Rules drive visibility + completion

After

1 code = 1 to many fields

All screens always present

Codes drive completion only

Source Files

1:many model→src/application/satisfy-code-definitions.ts

Screen array→src/application/screen-definitions.ts

Completion→src/application/resolve-screens.ts

Codes Drive Completion, Screens Stay Fixed

Three principles behind the Borrower UI application wizard.

Decision-Driven

Screens resolve from satisfy codes, not configuration

Screen Resolution

Always Present

All 8 screens always render. Codes track completion, never visibility.

Completion Model

Two Paths, One Interface

Simple forms and entity screens both converge on invalidate and advance

Submit Lifecycle

Navigation

Next: Portal Architecture

Policy YAML

TOE Series Hub

Signup, Application, & Portal

Domain Folders Own Their Slice

Decisions Drive Completion, Not Screen Order

Codes Map to Screens

Two Submit Patterns, One Interface

The Renderer Decides What to Show

From Rigid Rules to Flexible Codes

Codes Drive Completion, Screens Stay Fixed

Keyboard Shortcuts