Reactor: Event-Driven Computation

Data Changes Ripple Through the System

Every write triggers a cascade. Derived values stay in sync automatically.

Command

A data write happens

Triggers Fire

Registered watchers react

Events Cascade

New events trigger more watchers

Values Update

DTI, CLTV, decisions re-evaluated

ℹ️

Synchronous & deterministic — the full cascade completes before the request returns, so the borrower always sees up-to-date results.

Three Primitives Power Every Cascade

The reactor is built on typed, immutable data classes that chain together.

Commands

Requests to do something

CreateIncomeUpdateFile

Types→reactor/types/commands.py

Unions→reactor/types/__init__.py :226-324

Triggers

Match events, fire logic

EmitFinal

EmitTrigger→reactor/process.py :25-42

FinalTrigger→reactor/process.py :36

Events

Signals that something happened

CreatedIncomeDTIUpdated

Types→reactor/types/events.py

Unions→reactor/types/__init__.py :226-324

ℹ️

Invoked directly from views and services — not driven by ORM hooks. Those handle the downstream decision engine separately.

Triggers Either Continue or Terminate

Two trigger types. One continues the cascade, the other ends it.

Command Received

A typed command enters the reactor and triggers are matched

Emit Triggers

Produce new events — the cascade continues

Create IncomeCalculate DTIUpdate File

EmitTrigger→reactor/process.py :26

Final Triggers

Terminal — perform side effects only

Run DecisionLink BXP User

FinalTrigger→reactor/process.py :36

Run Decision→reactor/functions/run_decision.py

Link BXP→reactor/functions/link_bxp_borrower_user.py

ℹ️

Final triggers run last — after all emit triggers have settled. The cascade is fully resolved before any side effects execute.

The Cascade Loop Runs to Completion

Every command batch enters the same loop — match, fire, repeat until settled.

Commands In

A batch of typed commands enters the reactor

Entry→reactor/process.py :446-463

Normalize→reactor/process.py :421-443

Cascade Loop

Match trigger dependencies

Fire triggers → new events

Dedup already-fired

Final Triggers

Side effects execute after the loop settles

Loop→reactor/process.py :341-418

⚠️

Safety limit — the loop caps iterations to prevent infinite cascades. If exceeded, it raises an exception rather than silently stopping.

Commands and Events Are Typed Dataclasses

Most commands pair with a matching event. A few are fire-and-forget.

CreateIncome

Command

Source→reactor/types/commands.py :300-308

CreatedIncome

Paired event

Source→reactor/types/events.py :154-155

UpdateFileDTICached

Command

Source→reactor/types/commands.py :74-78

FileUpdatedDTICached

Paired event

Source→reactor/types/events.py :70-72

CreateFileEventDTI

Command

Source→reactor/types/commands.py :211-214

No event

Internal processing only

ℹ️

Frozen and immutable — all types are hashable dataclasses with slots. This enables deduplication and makes cascades fully inspectable.

Triggers Are Organized by Role

Four categories cover every registered trigger in the system.

Entity CRUD

Create, update, and delete for each entity type

IncomeLiabilityAssetLienEmploymentCreditTradeline

Examples→reactor/functions/create_income.py

→reactor/functions/create_liability.py

→reactor/functions/create_lien.py

Calculations

Derived values recomputed from entity changes

DTICLTVStable Income

DTI→reactor/functions/calculate_dti.py

CLTV→reactor/functions/calculate_cltv.py

Stable→reactor/functions/determine_stable_income.py

File Events

Bridge calculated values onto the borrower file record

Credit ScoreProperty ValueVerified Income

DTI Event→reactor/functions/create_dti_event.py

Credit→reactor/functions/create_credit_score_event.py

Final Triggers

Terminal side effects — run after the cascade settles

Run DecisionLink BXP User

Registry→reactor/process.py :44-323

Index→reactor/functions/__init__.py

ℹ️

Dependency-driven — each trigger declares which event types it watches. The loop matches events to dependencies automatically.

Derived Values Recompute Automatically

Derived values watch their dependencies and recompute automatically through the cascade.

DTI

Total monthly obligations divided by total income

LiabilitiesTradelinesIncome

Calc→reactor/functions/calculate_dti.py

Trigger Deps→reactor/process.py :196-209

CLTV

Combined loan-to-value from liens and property value

LiensLoan AmountProperty Value

Calc→reactor/functions/calculate_cltv.py

Trigger Deps→reactor/process.py :227-237

Stable Income

Are all employment records W2 with current status?

Employment

Calc→reactor/functions/determine_stable_income.py

Credit Score

Median per person, then minimum across all borrowers

Soft PullHard PullLender Provided

Calc→reactor/functions/create_credit_score_event.py :29-63

ℹ️

Automatic cascading — updating an income record triggers DTI recalculation, which updates the file, which can trigger a decision re-evaluation.

From CreateIncome to Run Decision

Trace what happens when a borrower adds an income record.

Add Income

A view issues a CreateIncome command

View→app/borrower/views/income.py :72-81

Test→tests/reactor/test_create_income.py

Calculate DTI

Trigger fires — recomputes debt-to-income ratio

Calc→reactor/functions/calculate_dti.py

Create DTI Event

Audit record created, emits cached value updates

Source→reactor/functions/create_dti_event.py

Update File

Cached DTI written to the file record

Source→reactor/functions/update_file.py

Run Decision

Final trigger fires after the cascade settles

Source→reactor/functions/run_decision.py

ℹ️

Parallel branches — adding income also triggers verified income checks. Multiple cascade paths resolve independently before final triggers run.

The Reactor Bridges Views to Decisions

Views call the reactor. The ORM bridges to the decision engine.

Application Views

Borrower views, admin views, order handlers

Borrower→app/borrower/views/income.py

Borrower→app/borrower/views/liability.py

Admin→svc/file/views/income.py

FE Test→borrower-interactions-ui/src/application/__tests__/use-reactor-mutation.test.ts

Reactor Cascade

Commands in → triggers fire → events cascade → file updated

ORM Flush

Dirty file detected → workflow automatically invoked

after_flush→lc/sas.py :230-248

Decision Engine

Policies re-evaluated → satisfy codes updated → UI refreshes

Final→reactor/functions/run_decision.py

ℹ️

Indirect connection — the reactor never calls the decision engine directly. The ORM detects file changes and triggers workflow evaluation automatically.

What to Remember About the Reactor

Three principles that explain the entire system.

Synchronous

The full cascade completes within the request. No background jobs, no eventual consistency.

Explicit

Every trigger is registered, testable, and inspectable. No hidden magic.

Type-Safe

Commands and events are frozen, hashable dataclasses. Enabling dedup and inspection.

Navigation

Next: Decision Engine

System Overview

Pricing Engine

Data Changes Ripple Through the System

Three Primitives Power Every Cascade

Triggers Either Continue or Terminate

The Cascade Loop Runs to Completion

Commands and Events Are Typed Dataclasses

Triggers Are Organized by Role

Derived Values Recompute Automatically

From CreateIncome to Run Decision

The Reactor Bridges Views to Decisions

What to Remember About the Reactor

Keyboard Shortcuts