FXpress · AI Co-Pilot for Cross-Border Remittance · Prototype Build Notes

What This Document Is

The Prototype Link page is the door. This page is what's behind it: how the widget actually works, what it does and does not do, and the architectural decisions that make it defensible as an AI-assisted money product. Reviewers and engineers can read this to understand the build without needing the source.

What the Widget Was Built To Demonstrate

The widget exists to prove the central design claim of FXpress: that an AI co-pilot can be genuinely useful for cross-border timing decisions without being given the power to move money or invent numbers. Three questions drove the scope:

• Does the read feel useful in real time? Live FX data, 30 days of central-bank history, a range position computed from it.
• Can the AI narrate without overstepping? Claude generates the language; deterministic code generates every number Claude is allowed to say, and the prompt forbids forecasting outright.
• Does it degrade gracefully? If Claude is unreachable, a templated voice built from the same real signal produces the same sentence. The user can see which voice is speaking.

The widget answers all three, live.

The Architecture

The widget runs in two layers that never cross.

Layer 1 — Deterministic engine (pure JavaScript, no AI)

When the user changes the amount or corridor, the widget runs this sequence in code:

1. Fetches 30 days of history for the corridor from Frankfurter (api.frankfurter.dev/v2/rates) — free, no key, CORS-enabled, sourced from 84 central banks. Today's rate is the last row of that series, so spot and history come from the same provider and the comparison is like-for-like. ExchangeRate-API (open.er-api.com) remains as a fallback if Frankfurter is unreachable.
2. Caches the series in fexi.hist.{code}, keyed by calendar day — one request per corridor per day, since the underlying data publishes daily.