TOE: System Architecture

Everything Runs Through Marketplace

Borrower and lender are just different API views of the same backend.

Borrower

Application wizard + portal

Cookie Auth /bxp endpoints

FE endpoints→borrower-interactions-ui/src/lib/endpoints.ts

Marketplace

Single Python backend serving both UIs

Decision Engine Pricing Engine Reactor PostgreSQL File Model

/bxp routes→lc/app/borrower/routes.py

/api routes→lc/svc/file/routes.py

Lender

Underwriting + verification

Session Auth /api endpoints

Two API namespaces, one backend

// Borrower — /bxp prefix, cookie auth
ENDPOINTS = {
  fileData: '/bxp/get-file',
  income:   '/bxp/income',
  decision: '/bxp/decision-result',
}
// Lender — /api prefix, session auth
endpoints = {
  file:           (id) => `/api/file/${id}`,
  income:         (id) => `/api/file/${id}/income`,
  decisionResult: (id) => `/api/file/${id}/decision-result`,
}

Every System Reads the Same File

One File = one loan application. Every entity branches from it.

File

identity→borrower name, SSN, DOB

property→address, type, value

loan→amount, term, type, purpose

derived→DTI, credit score, CLTV

SQLAlchemy model→lc/model/file.py

Income

views/income.py

borrower-created

Liability

views/liability.py

borrower-created

Employment

lc/schema/employment.py

borrower-created

Asset

lc/model/asset.py

borrower-created

Credit

lc/model/credit_data.py

system-created

Lien

lc/model/lien.py

lender-created

⚠️

Security Boundary

Lender-only fields like excluded and verified must never reach borrowers. The /bxp proxy strips them automatically.

Borrower UI - Application

Zod schemas that mirror these entity shapes on the FE

App schema→src/application/application.schema.ts

Field schemas→src/fields/schemas.ts

Deletes Are Soft by Default

Flagged, not removed. One exception: vendor-sourced credit tradelines.

Soft Delete

Record stays in the database, flagged as deleted

IncomeLiabilityAssetLienEmployment

reactor/functions/delete_<entity>.py

Hard Delete

Only for vendor-sourced credit tradelines replaced by a new pull

Credit Tradelines

reactor/functions/delete_credit_tradelines.py

ℹ️

Deletes still cascade — removing an income record triggers DTI recalculation just like adding one. The reactor treats all entity changes symmetrically.

No Submit Button — Everything Reacts

Every data change triggers re-evaluation automatically.

Flat Fields

Borrower updates a field

Name, address, loan amount — columns set directly, then commit

PATCHdecision engine only

View→lc/app/borrower/views/update_file.py

Entity CRUD

Borrower adds or edits a record

Income, liabilities, assets — Reactor recalculates derived values first, then commit

POST / PUT / DELETEreactor + decision engine

Income→views/income.py

Liability→views/liability.py

Asset→views/asset.py

Employment→views/employment.py

Both Paths Converge Here

after_flush detects a dirty File → Decision Engine re-evaluates all policies → satisfy codes update → screens react automatically.

automaticno user action needed

after_flush→lc/sas.py :230

Workflow→lc/engines/workflow/api.py

Reactor Deep Dive

Decision Engine

Everything Funnels Through the Workflow Layer

One orchestrator coordinates decision, reactor, and pricing.

after_flush

SQLAlchemy hook

Hook→lc/sas.py :230

Workflow Engine

Orchestrates stage progression — loads policy, calls decision engine, handles results

orchestrator

API→lc/engines/workflow/api.py

Decision Engine

Tri-logic YAML evaluation + condition dispatch

policy eval

API→lc/engines/decision/api.py

Input→lc/engines/decision/input.py

Policies→lc/engines/decision/policies/

Reactor

Event-driven cascade — derived values, order triggers

data compute

Process→lc/reactor/process.py

Pricing Engine

On-demand rate/APR/fee computation

on-demand

API→lc/engines/pricing/api.py

Calc→lc/engines/pricing/calc/

Same Data, Same Names, Same Rules

Contracts keep the repos in sync.

DATA CONTRACTS

Satisfy Codes

Code names in Borrower UI must exactly match BE enum values — maps codes to screens to fields

FE ↔ BE

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

Resolver→src/application/resolve-screens.ts

Tests→src/application/__tests__/satisfy-code-contract.test.ts

Field Name Chain

Same field name at every layer — JSON through dataclass through model column through DecisionInput

4 layers

DecisionInput→lc/engines/decision/input.py

File model→lc/model/file.py

Entity Schemas

Zod schemas in Borrower UI must mirror Marshmallow in marketplace — reference Cortex, strip lender-only fields

Marshmallow ↔ Zod

Marshmallow→lc/schema/asset.py, employment.py, file.py

Zod→src/application/application.schema.ts

Fields→src/fields/schemas.ts

INTEGRATION CONTRACTS

Decision Result

Both Borrower UI and Cortex consume the same endpoint — Borrower UI reads pass/fail, Cortex reads the full tree

polling

Borrower→lc/app/borrower/views/decision_result.py

Cortex→cortex/src/lib/decision.query.ts

Auth Patterns

Borrower UI uses httpOnly cookies, Cortex inherits marketplace session, Auth UI sets cookies

per-frontend

Views→lc/app/borrower/auth/views.py

Utils→lc/app/borrower/auth/utils.py

How to Ship Without Breaking the Chain

Rules for cross-repo work.

1. BE policy first

Finish YAML rules before aligning FE screens

sequence

2. FE adapts to BE naming

Same field names at every layer, never rename in FE

convention

3. Cortex as reference only

Use its schemas as a starting point, adapt Cortex's form patterns to card-based borrower UX

pattern

4. Reactor handles cascades

Never calculate DTI / CLTV in FE, submit data and let the reactor recalculate

boundary

DTI→reactor/functions/calculate_dti.py

CLTV→reactor/functions/calculate_cltv.py

5. FileData for values, decision-result for status

One endpoint for data, another for completion state

separation

FileData→views/get_file.py

Decision→views/decision_result.py

6. Entity APIs for repeatable data

Income, liabilities, assets use dedicated CRUD endpoints, not update-file

routing

Routes→lc/app/borrower/routes.py

Navigation

Next: User Journey

Borrower UI - Application

Reactor

Everything Runs Through Marketplace

Every System Reads the Same File

Deletes Are Soft by Default

No Submit Button — Everything Reacts

Everything Funnels Through the Workflow Layer

Same Data, Same Names, Same Rules

How to Ship Without Breaking the Chain

Keyboard Shortcuts