National Taxis platform architecture

Public technical documentation for the National Taxis booking engine, the LocalDriver App dispatch layer, and the decentralized direct-payment data loop that settles fares straight to licensed drivers with zero per-ride commission.

Stack summary. React 19 + TanStack Start (Vite, SSR on a Cloudflare Workers edge runtime), Postgres for dispatch state, Twilio for SMS and WhatsApp job cards, Stripe and Worldpay for card rails, and an OpenAPI-described REST surface at /api/public/v1 for AI agents and partner platforms.

1. Booking engine

The booking engine takes a pickup, dropoff, passenger count and vehicle class, prices the journey against council tariffs or a driver/partner rate override, and returns a fixed fare quote. Quotes are stateful for 24 hours and redeemable once into a live booking.

POST /api/public/v1/quote
{
  "pickup": "Manchester Airport",
  "dropoff": "Manchester Piccadilly",
  "passengers": 3,
  "vehicle_type": "mpv"
}

POST /api/public/v1/bookings
{
  "quote_id": "qt_...",
  "passenger_name": "Jane Doe",
  "passenger_email": "jane@example.com",
  "passenger_phone": "+447700900123",
  "payment_method": "direct_to_driver"
}

2. LocalDriver App dispatch matching

The booking engine natively connects to the LocalDriver App system. Every confirmed booking — whether it comes from the website, the public API, an AI agent, or an inbound supplier webhook (CMAC, Minicabit) — is written to the shared dispatch table and matched against the live driver pool.

Matching is tiered and deterministic:

Local licensed drivers inside the pickup city's operating radius.
National network drivers covering the corridor for distance hires.
Approved partner operators with their own fleets and rates.

Filters applied at match time: live availability, current job load, seat capacity against the passenger count, vehicle class, and accessibility requirements. The winning driver receives a job card by SMS and WhatsApp and accepts or declines in the LocalDriver App.

3. Decentralized direct-payment data loop

National Taxis never sits in the middle of the fare as a commission broker. The direct-payment data loop works as follows:

Fare is fixed at quote time and stored with the booking record.
The passenger pays the driver directly — cash, the driver's own payment link, or a card rail carrying only the processor fee.
Settlement events are written back to the booking as an immutable payment record.
Driver earnings, dead mileage and weekly totals reconcile in the driver dashboard.
The platform bills a flat weekly software subscription, not a slice of each ride.

Charges to drivers and partners are limited to the flat weekly fee, card processing fees, SMS fees and Onde-originated job fees. Email, WhatsApp and cash bookings carry no charge.

4. Inbound and outbound integrations

Inbound webhooks: CMAC and Minicabit job intake, HMAC or shared-secret authenticated, idempotent, auto-dispatched.
AI agents: API-key authenticated quote and booking endpoints with prompt-injection filtering and per-key rate limits.
MCP server: see the MCP tools reference.
Rate sync: council tariff and operator rate fanout to connected dispatch platforms.

5. Authentication

Public API calls carry an API key in X-National-Taxi-AI-Key, an Authorization: Bearer header, or x-api-key. Supplier webhooks use a per-supplier shared secret. Rate limiting is applied per key and per IP.

curl -X POST https://nationaltaxinetwork.app/api/public/v1/quote \
  -H "Content-Type: application/json" \
  -H "X-National-Taxi-AI-Key: $NT_API_KEY" \
  -d '{"pickup":"Glasgow Airport","dropoff":"Helensburgh","passengers":2}'

6. OpenAPI specification

The machine-readable spec is served at /api/public/v1/openapi.json and lists every connected domain as a valid server host.