Loan Origination Engine

A self-contained Xano template for a consumer-loan origination backend: an applicant applies, the engine scores them and runs a configurable risk-tier waterfall, and produces an auditable approve / conditionally-approve / refer / deny decision with ECOA adverse-action tracking. The whole submit → decision → status flow runs end-to-end on the seed data this repo ships, with no third-party credentials; real bureau, KYC, cash-flow, and notification providers are optional enrichment.

Consumer lending has two hard parts a demo usually skips: making a consistent credit decision, and being able to defend it afterward. Hand-coded approval logic drifts between loan officers, and when a regulator asks why an applicant was denied, "the system said no" isn't an answer — ECOA requires a specific adverse-action reason on the record. This template is a working decision engine that does both: a deterministic score feeds a configurable risk-tier waterfall to produce the outcome, every state change is written to an audit log, and every denial carries an ECOA adverse-action id and timestamp. It runs end-to-end on the shipped seed with no credentials, so you can trace the whole decision path before wiring in a real bureau.

backend/
  api/
    authentication/
      auth/
        login_POST.xs
        me_GET.xs
        signup_POST.xs
      authentication.xs
    loan_origination/
      api_group.xs
      applications_post.xs
      applications_status_get.xs
      applications_submit_post.xs
      demo_run_post.xs
      seed_post.xs
      webhooks_bureau_post.xs
      webhooks_kyc_post.xs
  function/
    audit/
      write_audit_log.xs
    auth/
      check_role.xs
    compliance/
      issue_glba_notice.xs
    decisioning/
      derive_internal_signals.xs
      run_decisioning.xs
      run_demo_scenario.xs
    external/
      call_credit_bureau.xs
      call_kyc.xs
      call_plaid.xs
    notifications/
      send_notification.xs
    pii/
      redact_applicant.xs
    validation/
      check_duplicate_applicant.xs
      check_prior_decisions.xs
  middleware/
    audit_trail.xs
    pii_redaction.xs
    role_guard.xs
  table/
    applicant.xs
    application.xs
    audit_log.xs
    decision.xs
    notification_log.xs
    risk_tier.xs
    user.xs
    webhook_event.xs
  task/
    expire_stale_applications.xs
  workflow_test/
    kyc_review_referred.xs
    low_score_denied.xs
    prime_auto_approved.xs
    subprime_conditional.xs
  workspace/
    production_2.xs

1. Scoring (function/decisioning/derive_internal_signals) — a deterministic, credential-free score (300–850) from income, debt-to-income, and loan-to-income. A demo heuristic, not a real bureau; a pure function, so it's fully unit-tested.
2. Waterfall (function/decisioning/run_decisioning) — evaluates score, DTI, loan amount, and KYC status against active risk_tier rows in priority order, picks the first eligible tier, and maps it to an outcome. Denials record an ECOA adverse-action reason.

Four outcomes, driven entirely by the seeded risk_tier rows: approved (auto-decision tier, KYC passing), conditionally_approved (tier not auto-decision-eligible), referred (tier matched, KYC needs review), denied (no tier matched; ECOA reason recorded). Because tiers live in the table, not code, you retune thresholds, rates, and eligibility by editing data — no redeploy.

Start with your coding agent. Paste the prompt below into a local MCP-capable coding agent — Claude Code, Cursor, Windsurf, and others. It installs the Xano CLI, connects Xano, and imports this template.

Start building in Xano: Access the prompt at https://go.xano.co/start-xano-with-template-skill and run it here with loan-origination-engine as your template.

The agent will walk you through the setup below.

1. Create a Xano workspace and push backend/:

xano workspace push -w <your-workspace-id> -d backend --force

2. Load the demo tiers + users (see Seed data).
3. Open the frontend, or drive it by API (below).

The whole flow runs credential-free on the seed. Demo logins (password Demo1234): broker@demo.test, underwriter@demo.test, applicant@demo.test.

Auth — api:<auth-group>: POST /auth/signup · POST /auth/login · GET /auth/me

Loan origination — api:loan-origination:

POST /applications                            create a draft application
POST /applications/{application_id}/submit    score + decision (accepts credit_score / kyc_status overrides)
GET  /applications/{application_id}/status     application + decision + PII-masked applicant
POST /demo/run                                 no-auth scenario runner
POST /webhooks/bureau                          feed a real credit-bureau result
POST /webhooks/kyc                             feed a real KYC result

• user — auth (roles: broker · underwriter · applicant)
• applicant — identity + financials; PII redacted on read
• application — the loan request + its lifecycle state
• risk_tier — the configurable waterfall rules (thresholds, rates, eligibility)
• decision — the outcome + ECOA adverse-action id/timestamp
• audit_log — append-only record of every state change
• notification_log — dispatched notifications
• webhook_event — inbound provider callbacks

• Unit tests (embedded in derive_internal_signals) — verify the scoring bands. xano unit_test run_all -w <id>
• Workflow tests (backend/workflow_test/) — drive the full decisioning path end-to-end for each of the four outcomes. xano workflow_test run_all -w <id>

Every .xs validates against the XanoScript language server.

The credential-free scorer is the default. To use real providers, set the relevant workspace env vars; results feed in through the webhook endpoints (which overwrite the derived score/KYC before decisioning). All external calls are wrapped, so missing credentials never break the flow.

Experian / Equifax     EXPERIAN_API_URL/KEY, EQUIFAX_API_URL/KEY   → POST /webhooks/bureau
Alloy / Persona (KYC)  ALLOY_API_URL/KEY/SECRET, PERSONA_API_URL/KEY → POST /webhooks/kyc
Plaid (cash flow)      PLAID_BASE_URL, PLAID_CLIENT_ID, PLAID_SECRET → submit with plaid_access_token
Twilio / SendGrid      TWILIO_*, SENDGRID_*                          → sent on decision