Onboarding Decision Engine

An externally-connected Xano template for KYC/CIP customer onboarding: it collects applicant identity, screens against OFAC, runs a provider waterfall (Alloy → Socure → Onfido) with Twilio Verify step-up, renders a compliance-officer final decision into an immutable 7-year CIP record, and exports a SAR data package for FinCEN filing.

The core flow depends on infrastructure you provision — an external MySQL 8 identity store and live provider credentials — so this repo ships the schema, seed rows, an internal-user seeder, and the setup guide to stand that up. For the full architecture, endpoint contracts, RBAC model, and compliance mapping, see DOCUMENTATION.md, which stays as its own repo file.

Onboarding a customer under KYC/CIP rules isn't a form — it's a regulated decision with a paper trail an examiner can pull years later. Teams end up gluing together identity vendors, OFAC screening, step-up verification, and a compliance sign-off, and the glue is where it breaks: a provider times out and the applicant is stuck, or a decision gets made but the record of why is incomplete. This template is that glue built correctly. Applicant PII is encrypted and the SSN hashed on intake, identity is screened against OFAC, run through the Alloy → Socure → Onfido waterfall with Twilio Verify step-up, decided by a BSA officer, and rendered into an immutable, signed 7-year CIP record — with a SAR data package ready to export. It is externally-connected — the core flow needs a real MySQL identity store and live provider keys — but it ships the schema, seed rows, and setup guide, so you stand up a known-good compliance architecture instead of designing the model from scratch.

What runs Xano-internal with no external setup: signup / login / me and the RBAC roles, the POST /auth/seed-users demo seeder, and the credential-free PII crypto self-tests. Everything that touches applicant / signal / decision / CIP data or calls a provider requires the external MySQL store and provider keys.

backend/
  addon/
    applicant_decisions.xs
    applicant_documents.xs
    applicant_signals.xs
    applicant_step_ups.xs
  api/
    authentication/
      auth/
        login_POST.xs
        me_GET.xs
        seed_users_POST.xs
        signup_POST.xs
      authentication.xs
    onboarding/
      api_group.xs
      final-decision_POST.xs
      run-waterfall_POST.xs
      sar-export_POST.xs
      start-onboarding_POST.xs
      step-up-document_POST.xs
  function/
    kyc/
      build_cip_record.xs
      call_alloy.xs
      call_ofac_screen.xs
      call_onfido.xs
      call_socure.xs
      call_twilio_verify.xs
      check_twilio_verify.xs
      decrypt_pii.xs
      encrypt_pii.xs
      evaluate_decision.xs
      hash_selftest.xs
      hash_ssn.xs
      pii_selftest.xs
      write_audit_log.xs
  middleware/
    compliance_audit.xs
    rbac_check.xs
  table/
    applicant.xs
    audit_log.xs
    cip_record.xs
    decision.xs
    document_artifact.xs
    kyc_signal.xs
    step_up_request.xs
    user.xs
    waterfall_rule.xs
  task/
    ofac_rescreening.xs
  workspace/
    alloy_socure_my_sql_onboarding_decision_engine_api_with_twilio_step_up.xs

1. Intake (start-onboarding) — creates the applicant, encrypts PII (function/kyc/encrypt_pii), hashes the SSN deterministically (hash_ssn), and runs an initial OFAC prescreen (call_ofac_screen).
2. Waterfall (run-waterfall) — calls the providers in cascade — Alloy (call_alloy), Socure (call_socure), Onfido (call_onfido) — records each result as a kyc_signal, then runs the centralized decision engine (evaluate_decision) to produce an outcome or step_up_required.
3. Step-up (step-up-document) — verifies a Twilio Verify OTP (call_twilio_verify / check_twilio_verify) and/or records a document artifact, then re-evaluates.
4. Final decision (final-decision) — a BSA officer locks the outcome and emits an immutable, signed CIP record (build_cip_record).
5. SAR export (sar-export) — assembles the full Suspicious Activity Report data package for FinCEN filing.

Every state change is written to the append-only audit_log (write_audit_log). RBAC is enforced inline in each endpoint; middleware/rbac_check and middleware/compliance_audit ship as reusable helpers. Note that the cascade order is hard-coded in kyc/evaluate_decision — the waterfall_rule rows are loaded and recorded but not yet interpreted as live rules; see DOCUMENTATION.md.

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 onboarding-decision-engine-alloy-socure-onfido-twilio as your template.

The agent will walk you through the setup below.

Install the Xano CLI, configure a profile, and push the backend:

npm install -g @xano/cli && xano profile:wizard
xano workspace push -w <your-workspace-id> -d backend --force

Then:

1. Seed the demo RBAC users — Xano-internal, no external deps (see Seed data).
2. Provision the external MySQL identity store and set the workspace env vars (see Environment variables + Seed data). The onboarding flow (start-onboarding → sar-export) requires these.
3. Open the frontend (see Frontend), or drive the API directly.

The credential-free PII self-tests and the auth/seed endpoints run immediately; the full flow comes online once MySQL and the provider keys are in place.

Auth endpoints issue and validate a bearer token; the onboarding endpoints require it.

Authentication — api:<auth-group>:

POST /auth/signup        create an ops user, return a token
POST /auth/login         return a token
GET  /auth/me            the authenticated user record
POST /auth/seed-users    create the three demo RBAC users (idempotent, no external deps)

Onboarding — api:onboarding-decision-engine:

POST /start-onboarding   create applicant, encrypt PII, hash SSN, initial OFAC screen
POST /run-waterfall      Alloy → Socure → Onfido → decision (or step_up_required)
POST /step-up-document   verify OTP / record a document, then re-evaluate
POST /final-decision     BSA officer finalizes → immutable CIP record (bsa_officer/admin)
POST /sar-export         full SAR data package for FinCEN (bsa_officer/admin)

The user (auth) table lives in Xano; the eight identity tables below live in the external MySQL store (seed/schema.sql mirrors their table/*.xs definitions).

• user — auth + RBAC role (ops · bsa_officer · admin); stays in Xano
• applicant — applicant identity + financials; SSN AES-256-CBC encrypted, hashed for lookup
• kyc_signal — per-provider result (identity_verification, fraud_score, watchlist, document_check, selfie_match)
• decision — the aggregated outcome + reason codes
• step_up_request — an OTP / document step-up triggered by a decision
• document_artifact — a document/selfie artifact and its external provider ID
• cip_record — the immutable, signed 7-year CIP record (schema-versioned)
• audit_log — append-only record of every state change and who performed it
• waterfall_rule — configurable waterfall rules (execution order, thresholds); loaded but not yet interpreted

Four applicant_* addons (applicant_signals, applicant_decisions, applicant_documents, applicant_step_ups) use Xano-internal db.query, so they return empty unless you mirror those tables into Xano; the shipped endpoints query MySQL directly and do not depend on them.

• Credential-free unit tests — the PII layer proves itself with no external deps:

  • kyc/pii_selftest — encrypt → decrypt round-trip (embedded test blocks)
  • kyc/hash_selftest — formatted and unformatted SSNs hash to the same deterministic token

  Set PII_ENCRYPTION_KEY / PII_ENCRYPTION_IV / SSN_HASH_SALT, then xano unit_test run_all -w <id>.

• The onboarding flow (start → waterfall → final-decision) crosses the external MySQL store and live providers, so it is verified after you provision those, per this guide — it is not run unattended.

Every .xs validates against the XanoScript language server.

The three PII/crypto keys are enough to run the credential-free self-tests; the MySQL connection string and provider keys are required for the onboarding flow. Set env vars with xano workspace push --env — a plain push does not apply the env block, and the committed workspace ships them empty.

Identity store    MYSQL_CONNECTION_STRING                          mysql://user:pass@host:3306/db
PII crypto        PII_ENCRYPTION_KEY, PII_ENCRYPTION_IV            AES-256-CBC key (32B) + IV (16B)
                  SSN_HASH_SALT, CIP_RECORD_SIGNING_KEY            SSN hashing + CIP signing (JWS HS256)
Alloy             ALLOY_BASE_URL, ALLOY_API_TOKEN                  evaluations + OFAC watchlist
Socure            SOCURE_BASE_URL, SOCURE_API_KEY                  Sigma + ID+
Onfido            ONFIDO_BASE_URL, ONFIDO_API_TOKEN                document + selfie checks
Twilio Verify     TWILIO_VERIFY_SERVICE_SID, TWILIO_AUTH_BASE64    OTP step-up (Base64 AccountSID:AuthToken)