Terra Dispatch

Overview

Dispatch is a white-label diagnostics storefront with an operations console behind it. It covers the whole kit lifecycle on the Vantage API: browse a catalogue, place an order, activate a kit, track fulfilment, and deliver results with the acknowledgement step Vantage requires. It runs against the hosted sandbox with no cloud accounts to set up, and without credentials it starts in demo mode on captured sandbox data.

What's inside

1. Storefront: catalogue browsing with the biomarkers each kit measures, at-home and in-lab ordering, and draw-site lookup.
2. Ops console: analytics, orders, the results queue and a webhook inbox for your team.
3. Kit activation: both the hosted flow and the programmatic API.
4. Signed webhooks: signature verification, an inbox and delivery debugging.
5. Results: FHIR parsing and display, plus the mandatory acknowledgement flow and escalations.
6. Sandbox simulation: drive an order through every state without a real kit.

Run it locally

You need the Terra CLI and Node.js 20 or later. Demo mode needs nothing else. For the sandbox, you need a dev ID and API key with Vantage access, which the Terra team enables.

1. Start in demo mode

terra examples clone vantage-web-app my-appcd my-appnpm installnpm run dev

The API runs on port 8787 and the app on 5173. Open localhost:5173 for a read-only walkthrough on captured sandbox data.

2. Connect the sandbox

cp .env.example .env# TERRA_DEV_ID=# TERRA_API_KEY=npm run setup

Fill in both keys, then npm run setup checks your environment and names anything missing. You can now browse the live catalogue and place sandbox orders.

3. Drive an order

Place an order in /shop, then use the simulate panel in /ops to move it through collection, lab receipt and results.

4. Receive webhooks

# TERRA_SIGNING_SECRET=npm run webhook:tunnel

Add your signing secret to .env and install the ngrok CLI. The tunnel registers its URL with Vantage, and events land in /ops/webhooks.

Next steps

Each Vantage capability lives in its own dependency-free file under src/server/lib/vantage/, so you can move them into your backend one at a time. Start with webhook-signature.ts: the HMAC covers the raw body, the timestamp is in seconds, and the comparison has to run in constant time. AGENTS.md maps what to copy and what to leave behind.