Desktop Underwriter (AUS)

Desktop Underwriter (DU) is Fannie Mae's Automated Underwriting System (AUS). The portal lets a user submit a loan or lead to DU, review the recommendation, findings, and any errors, and see the full history of past AUS runs — including runs placed directly in MeridianLink (MLM), so the history reflects MLM as the source of truth rather than only the runs the portal originated.

The user-facing surface is the Desktop Underwriter panel inside the Connect Services hub (?service=aus). The standalone /aus tab is retired and redirects there.

Two separate vendor seams

DU has a write path and a read path, and they are deliberately different capabilities so the vendor boundary stays clean.

The read adapter reuses the MLM identity adapter's OAuth token (MlmAuthProvider::apiUserToken()), so token minting lives in exactly one place. Both capabilities default to their null driver, so local and CI environments boot without MeridianLink credentials.

Submitting a run

POST /api/v1/loans/{loan}/aus (and the lead mirror) is asynchronous: it authorizes (aus.run), creates a pending AusSubmission, queues SubmitToAus, and returns 202. The job calls the du adapter, then DuResponseParser normalises the response into a recommendation, findings, risk factors, a casefile id, and — on failure — structured error_lines plus a machine-readable error_kind (e.g. missing_credit) the UI branches on. When DU returns a printable findings document it is stored as findings_html.

Mirroring past orders (always fresh, no button)

The portal's submission history is kept current with MLM automatically. There is no "sync" button — history refreshes purely on open.

When a user opens a loan or lead, the edit-time freshness gate (LoanFreshnessController::ensure / LeadFreshnessController::ensure) dispatches SyncMlmAusOrdersJob concurrently with the deep hydration and appraisal enrichment jobs (a separate queued job on the interactive appraisal lane, never inline in the request). The job runs HydrateMlmAusOrders (loan) or HydrateMlmLeadAusOrders (lead), which:

• read the loan's orders via the aus_orders capability using the loan's MLM reference number (loans.mlm_loan_number; for a lead, its vendor_reference_number, falling back to vendor_loan_number),
• upsert idempotently on aus_submissions.mlm_order_id (a best-effort backfill links a locally-placed run to its MLM order by casefile id so the same run is never shown twice),
• prune only MLM-sourced rows that are no longer reported — locally-placed runs (mlm_order_id null) are never touched, and an empty order list is a no-op, never a delete (a transient/permission empty must not wipe history).

The read adapter raises on transport failure rather than returning an empty list, so a failed read can never trigger a prune. MLM-sourced rows are labelled "From MeridianLink" in the submission history.

Permissions

aus.view gates listing and reading submissions; aus.run gates submitting a new run. Both are data-scoped through the per-user visibility scope like every other loan/lead resource.