Testing Guide — Demo UI

Before you start

• The local stack must be running. Ports 5001–5004 must respond. Start it with powershell -File ~/code/ach-poc/start-all.ps1.
• The UI makes CORS-enabled fetch calls directly from your browser to localhost. CORS is configured on both the process-api and the mock-api.
• Open the UI in a modern browser (Chrome or Edge). Safari is stricter about HTTPS→HTTP-localhost requests. If you’re on Safari, clone the UI locally and open it via http://localhost instead.
• The LIVE / OFFLINE status pill in the top-right of the UI confirms reachability. Green = ready. Red = the stack isn’t up.
• Use a Chromium DevTools console (F12) open on the Network tab to watch the real request/response bytes while you test.

UI layout — what each tab does

Scenario catalog — click-by-click

Each scenario below corresponds to one button in the Testing Scenarios tab. You can also run any of them manually from the Make a Transfer tab using the selections listed. Expected responses are the exact bytes returned by the pipeline on 2026-04-24.

{
  "status": "Fail",
  "status_code": 422,
  "data": {
    "error_message": {
      "type": "ContributionLimit",
      "code": 422,
      "errors": [{
        "message": "Projected contributions $20,000.00 exceed IRS limit $8,000.00 for RRH 2026"
      }]
    }
  }
}

{
  "status": "Success",
  "status_code": 200,
  "data": {
    "scheduled_execution_date": "2026-04-27",
    "cm_request_id": "a697e969-f2ba-4426-8d76-b951b07afcde"
  }
}

{
  "status": "Fail",
  "status_code": 422,
  "data": {
    "error_message": {
      "type": "HsaEligibility",
      "code": 422,
      "errors": [{ "message": "HSA contribution requires HDHP coverage" }]
    }
  }
}

{
  "status": "Success",
  "status_code": 200,
  "data": {
    "scheduled_execution_date": "2026-04-27",
    "cm_request_id": "..."
  }
}

{
  "status": "Fail",
  "status_code": 422,
  "data": {
    "error_message": {
      "type": "ContributionYear",
      "code": 422,
      "errors": [{ "message": "Prior-year 2025 contribution window closed (after Apr 15)" }]
    }
  }
}

{
  "status": "Success",
  "status_code": 200,
  "data": {
    "scheduled_execution_date": "2026-04-27",
    "cm_request_id": "..."
  }
}

{
  "status": "Success",
  "status_code": 200,
  "data": {
    "scheduled_execution_date": "2026-04-27",
    "cm_request_id": "..."
  }
}

{
  "status": "Success",
  "status_code": 200,
  "data": {
    "scheduled_execution_date": "2026-04-27",
    "cm_request_id": "..."
  }
}

{
  "status": "Success",
  "status_code": 200,
  "data": {
    "scheduled_execution_date": "2026-04-27",
    "cm_request_id": "b2326ec5-3f83-4a96-b6fb-6f2a3f50c618"
  }
}

{
  "transaction_id": "DEMO-999",
  "status": "canceled-stub"
}

What to check in the API Log panel

• Every submit logs the real request payload and response body in the right-side API Log panel. No network tab needed for a quick read.
• For failures, the log shows the rule-service type field (ContributionLimit, HsaEligibility, ContributionYear) — this tells you exactly which Wave 2 service fired.
• For successes, the log shows the returned cm_request_id. You can search the local process-api log at ~/.local/log/ach-poc/process-api.log by that id to trace the request through the orchestrator.
• The panel also shows the HTTP status code and round-trip timing. Times under 200 ms are normal for the local stack.
• Responses are colour-coded: green for 200, red for 422, orange for 4xx non-422, grey for network errors.

Validation checklist — sign-off criteria

Run the 10 scenarios end-to-end before declaring the UI demo-ready. Tick each item as you go.

• LIVE pill shows GREEN on first page load.
• TO dropdown populated with at least 60 accounts, grouped by category.
• Scenario 1 (over-limit) returns ContributionLimit 422 with the exact $20k / $8k / RRH message.
• Scenario 2 (happy path) returns 200 with a fresh cm_request_id on every click.
• Scenario 3 (HSA no HDHP) returns HsaEligibility 422.
• Scenario 4 (HSA success) returns 200.
• Scenario 5 (prior year) returns ContributionYear 422 with the Apr 15 mention.
• Scenarios 6, 7, 8 return 200 (SEP + SIMPLE + brokerage).
• Scenario 9 (RMD withdrawal) returns 200 on /ach/withdrawal/with-reason.
• Scenario 10 (cancel stub) returns 200 with "canceled-stub" status.
• API Log panel shows the real request and response bytes for every submission.

Advanced — crafting your own payloads

The 10 scenarios cover the happy and sad paths for every Wave 2 rule, but you can go beyond them by posting directly against the local stack.

The snake_case payload shape

{
  "transaction_request": {
    "account_id": 10000024,
    "lpl_account_number": "10000024",
    "amount": "3000.00",
    "firm_id": 1,
    "transaction_type": "ACHC",
    "origin_id": "AccountView",
    "beta_item_seq_no": "1",
    "requested_execution_date": "2026-04-24T12:00:00Z",
    "rep_id": "ABC1",
    "client_id": 1024,
    "transfer_reason": "IRA Contribution",
    "transfer_type": "contributionType",
    "user_context": { "advisor_user_name": "TestAdvisor" }
  },
  "contribution_metadata": {
    "contribution_year": 2026,
    "contribution_type": "Regular",
    "actor_type": "Investor",
    "ytd_contributions_amount": 0,
    "is_hdhp_covered": false,
    "rollover_type": null
  }
}

Enum values you can set

Sample cURL that reproduces Scenario 1 outside the UI

curl -X POST http://localhost:5001/ach/contribution \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_request": {
      "account_id": 10000024, "lpl_account_number": "10000024",
      "amount": "20000.00", "firm_id": 1, "transaction_type": "ACHC",
      "origin_id": "AccountView", "beta_item_seq_no": "1",
      "requested_execution_date": "2026-04-24T12:00:00Z",
      "rep_id": "ABC1", "client_id": 1024,
      "transfer_reason": "IRA Contribution", "transfer_type": "contributionType",
      "user_context": {"advisor_user_name": "TestAdvisor"}
    },
    "contribution_metadata": {
      "contribution_year": 2026, "contribution_type": "Regular",
      "actor_type": "Investor", "ytd_contributions_amount": 0
    }
  }'

This is the exact payload the UI sends when you click Scenario 1. Paste it in a terminal (Git Bash, WSL, or PowerShell with curl.exe) and you’ll get the same 422 ContributionLimit response.