bespoke.flights
Private aviation charter marketplace. Travelers submit multi-leg flight requests, certified charter operators compete with quotes, and bookings happen directly — no broker markup.
Stack: Next.js 16 · React 19 · TypeScript · Tailwind CSS 4 · Postgres (Neon via Vercel) · Stripe (Checkout + Connect) · Resend (email) · Vercel Cron
How It Works
Traveler submits request → Matching engine scores operators → RFQs dispatched via email/SMS
↓
Operators quote from their dashboard
↓
Traveler compares and accepts a quote
↓
Booking confirmed
There are three user roles — customer, operator, and admin — each with their own authenticated views and workflows.
Who can see what
- A customer sees only their own requests, every quote on them, and which operators were invited (without the operators' contact details).
- An operator sees requests that are open to quotes, or that it was invited to or has quoted; only its own quote on each; and the customer's contact details only after its quote has been paid for.
- Admins see everything. The rules live in
src/lib/access.ts and are covered by src/app/api/authz.test.ts.
- Cancelling an unpaid request is for its customer (or an admin). A paid booking is cancelled through the refund flow so money moves with the status.
- Rate limits (
src/lib/rate-limit.ts, stored in the rate_limits table so they hold across serverless instances): sign-in/sign-up 10 per 15 min per IP; new booking requests 5 per hour per user; trip-sheet emails and staff test alerts 10 per hour; manual discovery runs 3 per hour. Exceeding one returns 429 with Retry-After.
Customer Workflow
-
Two booking forms. The home page and /book use the ticket form: each leg is a paper ticket with From, To, date, departure time and guests printed into it; Add a leg issues another ticket starting where the last one lands (src/components/booking/ticket-booking-form.tsx). The step-by-step classic form is at /book/classic and is described below. Each request records which form produced it (booking_requests.form_variant); the admin dashboard compares requests and bookings per form. Once every leg is complete, a signed-in traveler's request goes out automatically after 5 seconds (any change restarts the timer; Wait pauses, Send now skips it; a restored draft waits). A visitor sees the account form as soon as the route is complete. There is no passenger cap; operators split large groups across aircraft.
-
Build an itinerary at /book/classic. "Start Booking" on the home page goes straight here; no account is needed. Add origin, destination, date and time for each leg; multi-leg trips (A → B → C → A) are supported. Each leg shows its great-circle distance (nm, mi, km) once both airports are known, and the route header totals the trip. Set leg collapses a finished leg to a summary with Edit and Cancel leg (undoable); Add a leg sits at the bottom right of the last leg. Airport coordinates come from OurAirports (src/lib/airports.ts); the math is in src/lib/distance.ts. Special requests are chips: preset tags (pets, surfboards, ground transportation, medical devices and more) and up to six of the traveler's own, added with Add your own and edited or removed in place (src/lib/bookings/request-tags.ts). Both are kept in the draft and folded into the request's notes on submit, so operators see them wherever special requests appear. The itinerary is saved in the bf_booking_draft cookie on every change (30 days, SameSite=Lax), so reloading or returning later restores it.
-
Sign up or sign in at submit. A visitor without a session gets an inline account step on /book. After registering or signing in, the server turns the saved itinerary into a booking request, clears the cookie, and opens the new request. Signing in through /login or /register with a saved itinerary does the same. Signed-in travelers submit directly.
Wherever a trip that is being booked appears (the booking form's live summary, the account step, request lists and pages for travelers, operators and admins, the Stripe Checkout line item, and the booking emails), it shows every detail: route, each leg's date and time ("Any time" if none was given), passengers, and special requests ("None" if empty). The shared component and produce this.
Operator Workflow
-
Register at /register?role=operator. Account starts in pending status.
-
Configure profile at /operator/settings once approved by an admin:
- Preferred contact method (email, text, or both)
- Charter sales email and SMS phone number
- Safety rating (ARGUS Platinum through Part 135 Certified)
- Market coverage (10 regions: Hawaii inter-island, mainland→Hawaii, US West/East/Southeast/Central/Southwest, Caribbean, transatlantic, Pacific)
- Fleet categories (VLJ through ultra-long range)
- Hawaii-capable and transoceanic flags
- FAA certificate number
-
Receive inbound RFQs at /operator/inbound. These are charter requests automatically matched to the operator's profile by the matching engine. Each card shows the route, pax count, dates, match score, and time since receipt.
-
Submit a quote inline — price, aircraft (from fleet inventory), valid-until date, and an optional message. Work out the price opens a worksheet (src/lib/quotes/worksheet.ts): leg hours estimated from distance and the aircraft's cruise speed, hourly rate, positioning, daily minimum, fuel surcharge, crew overnights, landing/handling, catering, other costs, margin, federal excise tax (7.5% default) and per-passenger segment fees; Use as the price fills the price. The worksheet is saved in quote_worksheets, readable only by the quoting operator (GET /api/quotes/[id]/worksheet), and can be edited when revising. Travelers and admins never see it. One click creates the quote and marks the outreach log as responded.
-
Browse all demand at /operator/requests to see every open request on the platform, not just auto-matched ones.
-
Share a booking with the team. Once a booking is paid, the winning operator's request page shows Share with your team:
- Private link to a read-only trip sheet at
/trip/<token>. No login is needed to view it. It shows legs with dates and times, aircraft, passengers, special requests, and the lead passenger's name, phone and email. It prints cleanly and is not indexed by search engines.
- Email the trip sheet to up to 20 colleagues.
- Calendar file (
/trip/<token>/calendar): one event per leg, at the requested local time, or all-day when no time was given.
Admin Workflow
- Dashboard at
/admin/dashboard — system-wide stats (users, operators, requests, quotes, bookings) plus the operator discovery pipeline summary.
- Operators at
/admin/operators — approve or suspend, Add operator (company, contact, sign-in email, certificate, status), and edit any operator's company profile: name, status, certificate, request contact, safety rating, markets, aircraft categories, range, platform fee override, notes.
- Users at
/admin/users — search and filter by role, Add user (any role; an operator needs a company name), and edit name, phone and role. An admin cannot change their own role, and the last admin cannot be demoted. Making someone an operator creates their company profile; a former operator keeps theirs. Role changes apply on the user's next request (the role is read from the database each time). New accounts get a temporary password shown to the admin once; in production the first sign-in with it moves the account to Neon Auth. Routes: POST /api/admin/users, PATCH /api/admin/users/[id], POST /api/admin/operators, PATCH /api/admin/operators/[id].
- View all requests at
/admin/requests.
- Operator discovery at
/admin/discoveries — manage FAA-discovered operators (details below).
- Payments at
/admin/payments — gross bookings, net platform fees, refunds, disputes; issue full or partial refunds.
Automatic Outreach System
When a customer submits a booking request, the matching engine runs synchronously before the API response returns.
Matching Algorithm
Each approved operator is scored on a 100-point scale:
| Factor | Weight | Logic |
|---|
| Market coverage | 40% | Operator's configured markets include the classified market for this route |
| Fleet type match | 20% | Operator's fleet categories can serve the passenger count and route distance |
| Safety rating | 25% | ARGUS Platinum / Wyvern Wingman = 25, Gold = 18, Part 135 = 10 |
| Past performance | 15% | 3 points per accepted quote, capped at 15 |
Penalties are applied for route/capability mismatches:
- Route requires Hawaii but operator is not
hi_capable: −30
- Route exceeds 3,000 nm but operator is not
transoceanic: −20
The top 10 operators scoring above 20 are dispatched an RFQ.
Market Classification
Routes are classified into one of 10 markets based on ICAO airport codes:
| Market | Examples |
|---|
hi_inter | PHNL ↔ PHOG, PHKO, PHLI |
mainland_hi | KLAX → PHNL, KJFK → PHNL |
west | KLAX, KSFO, KSEA, KSAN, KPDX |
east | KJFK, KTEB, KBOS, KPBI, KIAD |
se | KATL, KMIA, KFLL, KTPA, KMCO |
central | KORD, KDEN, KMSP, KDTW |
sw | KDFW, KHOU, KLAS, KPHX |
carib | TNCM, TJSJ, MYNN |
transatl | EGLL, LFPB, EDDF |
pacific | Pacific island codes |
RFQ Delivery
Matched operators receive a branded HTML email via Resend containing the full itinerary, passenger count, notes, and a link to submit their quote. Operators whose contact method is text or both also get a text through Twilio. Without a RESEND_API_KEY, emails are logged to stdout. Without Twilio credentials, or in test mode, texts are logged instead.
Quoting by replying to the RFQ email
When INBOUND_EMAIL_SECRET is set, each RFQ email gets a Reply-To of quotes+<token>@<domain> (outreach_log.reply_token; the domain is EMAIL_REPLY_DOMAIN, else the domain of EMAIL_FROM) and tells the operator they can reply with a price. Point the email provider's inbound webhook at POST /api/webhooks/inbound-email with Authorization: Bearer $INBOUND_EMAIL_SECRET; the body is {from, to, subject, text, html} or {data: {...}}. The first dollar amount in the reply's own text (above any quoted original) is the all-in price; an N-number matching the operator's fleet sets the aircraft and valid 2026-11-01 sets the validity; the rest of the reply is the message shown to the traveler. The token is the credential, and the sender must be the operator's contact or sign-in address. The quote is created through the same path as the dashboard (quotes.source = 'email'), the traveler is notified, and the operator gets a confirmation or a "quote not recorded" email with the reason. src/lib/quotes/by-email.ts.
Operator Discovery Pipeline
A weekly automated pipeline finds new charter operators and invites them to join the platform.
How It Works
- Vercel Cron triggers
GET /api/cron/weekly-discovery every Monday at 8:00 AM HST (18:00 UTC), sending Authorization: Bearer $CRON_SECRET. The route refuses every call when CRON_SECRET is unset. Each FAA request has an 8 s timeout and the scrape stops after 35 s so storing and emailing fit the 60 s function limit; states that were skipped or failed are listed in the run's errors.
- FAA scraper queries
av-info.faa.gov for Part 135 on-demand air taxi certificate holders, processing 10 states per run and rotating through all US states across ~5 weeks.
- Deduplication skips operators already in the
discovered_operators table or registered on the platform.
- Storage inserts new records. Since the FAA registry does not publish email addresses, most land with status
no_email.
- Invite emails are sent via Resend to any discovered operators that have an email address and status
new. The branded email explains the marketplace, links to registration, and includes the operator's FAA certificate number.
Discovery Statuses
| Status | Meaning |
|---|
new | Has email, ready to send invite on next run |
no_email | Found in FAA registry but no email — admin needs to add one |
emailed | Invite sent via Resend |
registered | Operator created an account on the platform |
opted_out | Marked by admin as not interested |
bounced | Email delivery failed |
Admin Discovery UI
At /admin/discoveries, admins can:
- Filter by status, state, or search by company name / cert number
- Click Add Email on any
no_email operator — status auto-upgrades to new, and the next cron run sends the invite
- Click Opt out to suppress future contact
- Click Run Discovery Now to manually trigger the pipeline (admin session; 3 runs per hour)
- View pipeline stats in the dashboard: total discovered, ready to email, need email, invited
Payments
Stripe Checkout collects the customer's payment as a destination charge to the operator's Stripe Connect Express account. The operator is the settlement merchant (on_behalf_of); the platform keeps its commission as the application_fee_amount.
Flow
Customer clicks "Accept & Pay" → POST /api/payments/checkout
→ payments row (pending) + Stripe Checkout Session (expires in 1 h)
→ customer pays on Stripe → redirected to /requests/[id]?checkout=success
Stripe → POST /api/webhooks/stripe (signature verified)
→ checkout.session.completed (paid) → payment succeeded, quote accepted,
other quotes rejected, request booked, receipt + operator emails sent
- Quotes are accepted only through payment.
PATCH /api/quotes/[id] declines (traveler), or withdraws / revises (the quoting operator, while pending).
- One open checkout per request. Starting a checkout for a different quote expires the previous session.
- Double payment protection. If two sessions are both paid, the second one is refunded automatically, including the transfer reversal.
- Bank payments (ACH). The payment shows as
processing until checkout.session.async_payment_succeeded or ..._failed arrives. The request is not booked until funds clear.
- Expired quotes (
valid_until in the past) cannot be paid. The daily lifecycle job marks them expired.
- Webhooks are idempotent. Event IDs are recorded in
payment_events, and every handler can safely run more than once. If processing fails, the endpoint returns 500 so Stripe retries.
Receipts
/requests/[id]/receipt (owner or admin) is an invoice-style, printable receipt: number BF-<year>-<payment id padded to 6>, billed-to, operator legal name with FAA certificate and safety rating, legs, aircraft and tail, each charge (booking and any paid itinerary changes) with date and payment method when known, refunds, and the net. It is linked from the trip page and the receipt email. Quote cards show the operator's certificate number and safety rating under the company name.
Cancelling a paid booking
A traveler cancels from the trip page (Cancel trip → confirmation panel showing the refund). The refund follows the operator's cancellation policy (operators.cancellation_policy, set at /operator/settings), measured from the first leg's departure (its local date and time, or 23:59 when no time was given):
| Window | Default | Refund |
|---|
≥ full_refund_hours before departure | 72 h | 100% |
≥ partial_refund_hours | 24 h | partial_refund_bps (default 5000 = 50%) |
| Closer than that | | none |
GET /api/booking-requests/[id]/cancel previews the refund; POST performs it (owner or admin): the refund goes through the normal refund path (transfer reversal and fee return), the request becomes cancelled, pending quotes are rejected, both sides get a cancellation email and the operator's staff are alerted. Unpaid requests are still withdrawn with PATCH /api/booking-requests/[id] {status:'cancelled'}.
Changing a booked trip
On a booked trip the traveler can Request a change (new legs, guest count, special requests) from the trip page. One change can be pending at a time (change_requests table). The winning operator sees it on their request page and in the Change requests section of the company board, and either:
- accepts at the same price: the booking is updated at once, both sides are emailed;
- accepts at a higher all-in price: a payment for the difference is created (
payments.change_request_id); the change is applied when it is paid, through the normal fulfillment path (webhook or the stub "simulate" button);
- accepts at a lower price: the difference is refunded and the change applied;
- declines with a note: the traveler is emailed and the booking stands.
Routes: GET/POST /api/booking-requests/[id]/changes, PATCH /api/change-requests/[id] with {action: 'accept' | 'decline' | 'withdraw', newPriceCents?, note?}. Staff alerts of kind change go to staff subscribed to Change requested.
Empty legs
Operators list repositioning flights at /operator/empty-legs (empty_legs table): aircraft from the fleet, route, date, optional time, date flexibility (±0–7 days), seats, an all-in price for the whole aircraft and a note. Listings are public at /empty-legs (filter ?from=HNL&to=OGG, IATA or ICAO) and show the operator's legal name, certificate and safety rating.
- Booking. "Book this flight" creates a request in status
quoted with one leg and a pending quote at the listed price (quotes.is_empty_leg = 1, quotes.empty_leg_id, valid until the departure date) and opens the trip page, where the traveler pays through the normal checkout. A visitor's choice is kept in the bf_empty_leg cookie and booked right after sign-in or sign-up. Several travelers may hold a quote on the same listing; the first payment to clear marks the listing booked, withdraws the other quotes and emails those travelers. Checkout and fulfillment refuse a listing that is no longer listed, so a late payment is refunded automatically. A cancelled booking puts the listing back on the market if its date has not passed. The empty-leg commission from the business model applies.
- On requests. A traveler's open request shows listed empty legs that fit its single leg (same route, date within the listing's flex window, enough seats). The operator's inbound RFQ card shows its own matching listings with a one-click quote at the listed price (
POST /api/operator/empty-legs/[id]/quote).
- Lifecycle. Operators change the price or withdraw a listing (pending quotes made from it are withdrawn, travelers emailed); the daily lifecycle job expires listings whose date has passed.
Routes: GET /api/empty-legs (public), POST /api/empty-legs/[id]/book, GET/POST /api/operator/empty-legs, PATCH /api/operator/empty-legs/[id], GET /api/booking-requests/[id]/empty-legs. Service: src/lib/empty-legs/service.ts.
Messaging
Travelers and operators talk in the app instead of by phone or email. One thread exists per (request, operator) once that operator has quoted (messages table, ≤ 2000 characters per message). On the trip page each quote has Message operator (expanded for the accepted quote); the operator's request page has the conversation with the traveler. Threads poll every 15 seconds. Phone numbers and email addresses are never part of the thread payload.
GET/POST /api/booking-requests/[id]/messages?operatorId= (operators omit operatorId; ?after=<id> returns only newer messages). Admins can read but not post. A new message emails the other side with a link to the thread, at most once per thread and recipient every 10 minutes (message_notifications), and raises a message staff alert for the operator on every traveler message.
Platform fee
The business model is configured by an admin at /admin/settings (stored as JSON under platform_settings.key = 'business_model', see src/lib/business-model.ts): default operator commission, subscriber-tier commission, empty-leg commission, launch-partner promotion (rate, booking cap, end date), processing pass-through and quote ranking are applied at checkout; the remaining fields (traveler fee, subscription price, ancillary margin, payout hold, referral fee, affiliation disclosure) are recorded for features that do not exist yet. PLATFORM_FEE_BPS (default 500 = 5%) is only the fallback before an admin saves a commission. Commission precedence: operators.platform_fee_bps override → launch promo (operators.launch_partner = 1) → empty leg (quotes.is_empty_leg = 1) → subscriber plan (operators.plan = 'subscriber') → default. The fee is rounded to the nearest cent. Stripe's processing fees come out of the platform's share unless pass-through is on.
Refunds and disputes
Admins refund from /admin/payments, in full or in part. Refunds use reverse_transfer and refund_application_fee, so the operator's payout and the platform fee are returned in proportion to the amount refunded. A full refund cancels the booking. Refunds made in the Stripe dashboard are synced through charge.refunded. charge.dispute.* events record a dispute's status on the payment.
Payment statuses
| Status | Meaning |
|---|
pending | Checkout session open |
processing | Bank payment submitted, not yet cleared |
succeeded | Paid; request booked |
partially_refunded / refunded | Refunded; a full refund cancels the booking |
failed | Checkout creation failed or the bank payment failed |
canceled | Session expired or replaced by a newer checkout |
Modes
| Mode | When | Behavior |
|---|
stub (test mode) | APP_TEST_MODE=true, in any environment; a Stripe key is ignored | Payments are simulated (see Test mode) |
stripe | STRIPE_SECRET_KEY set | Real Checkout and Connect |
stub | No key, NODE_ENV ≠ production | Payments are simulated: the request page shows a "Simulate successful payment" button, and payout setup completes instantly |
disabled | No key in production | Checkout returns 503, so no booking can be made without payment |
Test mode
Set APP_TEST_MODE=true (for example on a Vercel deployment) to try the full flow with dummy transactions:
- Payments are simulated. "Accept & Pay" leads to a "Simulate successful payment" button; no card is charged. Operator payout setup completes instantly, without a Stripe account. Admin refunds work and move no money. Stripe webhooks are refused.
- A banner on every page says the site is in test mode and lists the demo logins.
- Demo data loads automatically the first time the app connects to an empty database: the test accounts below, three approved operators with fleets, two requests (one with two quotes ready to pay), and sample FAA discoveries. A database that already has users is never touched.
To go live: remove APP_TEST_MODE, set the Stripe variables, and delete the demo accounts (or start from a fresh database).
Stripe setup
- Put the secret key in
STRIPE_SECRET_KEY on the Vercel project (Production), or connect the Stripe integration to the project so it adds it. Redeploy.
- Enable Connect (Express accounts) on the Stripe account, so operators can link payout accounts.
- Open Admin → Payments. The Stripe setup checklist checks the key (test or live), the account (charges, payouts), Connect,
APP_URL, and webhooks. Create webhooks registers both endpoints at <APP_URL>/api/webhooks/stripe (payment events on the platform account; account.updated on connected accounts) and stores their signing secrets in platform_settings, so nothing is copied by hand (src/lib/payments/stripe-setup.ts). Recreating replaces endpoints at the same URL.
STRIPE_WEBHOOK_SECRET / STRIPE_CONNECT_WEBHOOK_SECRET still work and take precedence.- Local testing:
stripe listen --forward-to localhost:3000/api/webhooks/stripe with its secret in STRIPE_WEBHOOK_SECRET.
Quote lifecycle
- Withdraw: an operator withdraws a pending quote (
PATCH /api/quotes/[id] {status:'withdrawn'}) from the request page; the traveler is emailed and the operator may quote again (the partial unique index only counts pending and accepted quotes).
- Revise: an operator changes the price, message, valid-until date or aircraft of a pending quote (
PATCH /api/quotes/[id] {priceCents?, message?, validUntil?, aircraftId?}). The old price is kept in quotes.previous_price_cents and revised_at is set; the traveler receives a "Quote revised" email and the quote card shows the previous price.
- Daily lifecycle (
GET /api/cron/daily-lifecycle, 10:00 UTC via vercel.json, bearer CRON_SECRET, or POST as an admin): expireQuotes sets pending quotes past valid_until to expired (one email per request to the traveler), completeTrips sets booked requests whose last leg is before today to completed (traveler emailed with a receipt link), and expireEmptyLegs sets listed empty legs whose date has passed to expired. src/lib/lifecycle.ts. The quotes.status CHECK constraint gains expired through a guarded DO block in SCHEMA_BLOCKS that runs once per database.
Email System
All email is sent through Resend's API via src/lib/email/resend.ts. Templates (src/lib/email/templates.ts):
| Template | Trigger | Content |
|---|
| Operator Invite | Discovery pipeline or manual trigger | Introduces Bespoke Flights, explains the marketplace model, links to /register?role=operator |
| RFQ Notification | Customer submits a booking request | Full itinerary, passenger count, match score, link to /operator/inbound |
| New quote / Quote revised | Operator submits or revises a quote | Sent to the traveler: operator, aircraft, all-in price, validity, link to compare |
| Payment Receipt | Payment succeeds | Sent to the customer: route, dates, operator, aircraft, total paid, receipt link |
| Booking Confirmed | Payment succeeds | Sent to the operator: itinerary, quote amount, platform fee, payout |
| Booking Cancelled | Traveler cancels a paid booking | Both sides: itinerary, amount paid, refund, policy |
| Change request | Proposed, accepted (with or without payment due), applied, declined | Proposed vs current itinerary, new price, operator note |
| New message | A message arrives in a thread (≤ 1 per thread and side per 10 min) | Sender and a link to the thread; the body stays in the app |
| Status update | Request withdrawn, quote declined or withdrawn, quotes expired, trip completed | One-paragraph notice with a link |
| Trip Sheet | Operator emails a booking to colleagues | Itinerary and the private trip sheet link |
| Staff Alert | Booking, cancellation, new request, change request or message, per staff preferences | Itinerary, passengers, special requests, aircraft, lead passenger and a link |
Texts go through Twilio (src/lib/notify/sms.ts). Phone numbers are normalized to E.164: 10-digit numbers are treated as US/Canada.
A sendBatch helper handles rate limiting (1 email/second for Resend's free tier). Without RESEND_API_KEY set, all emails are logged to the console in stub mode.
Project Structure
src/
├── app/
│ ├── (admin)/admin/ # Admin pages: dashboard, users, operators, requests, discoveries
│ ├── (auth)/ # Login, register
│ ├── (customer)/ # Book, requests, account, dashboard
│ ├── (operator)/operator/ # Dashboard, inbound, requests, quotes, fleet, settings
│ └── api/
│ ├── admin/ # Admin endpoints: operators, users, discoveries
│ ├── auth/ # Login, logout, register
│ ├── booking-requests/ # CRUD + auto-outreach on POST
│ ├── cron/ # weekly-discovery (Vercel Cron)
│ ├── fleet/ # Operator aircraft management
│ ├── operator/ # Inbound RFQs, settings
│ ├── outreach/ # Outreach log queries
│ ├── payments/ # Checkout creation, stub-mode simulation
│ ├── quotes/ # Quote decline (acceptance is via payment)
│ └── webhooks/stripe/ # Stripe webhook receiver
├── components/
│ ├── admin/ # Operator approval actions
│ ├── booking/ # Quote accept/decline buttons
│ ├── layout/ # Header with role-based nav
│ ├── operator/ # Outreach status display
│ └── ui/ # Badge, Button, Card, Input, Select, Table, AirportInput
└── lib/
├── auth.ts # Neon Auth sessions (production); bcrypt + JWT cookie (development)
├── access.ts # Who may read or change a booking request
├── rate-limit.ts # Database-backed fixed-window limits
├── airports.ts # Airport code data
├── types.ts # All TypeScript interfaces + market/fleet constants
├── validations.ts # Zod schemas for all API inputs
├── db/
│ ├── index.ts # Postgres access: pg pool (Neon) or embedded PGlite
│ ├── queries.ts # Shared query helpers (batched legs, quote counts)
│ ├── schema.ts # Full DDL: users, operators, aircraft, booking_requests,
│ │ # booking_legs, quotes, outreach_log, discovered_operators
│ └── seed.ts # Test data: 4 operators, 2 customers, 1 admin,
│ # 2 booking requests, sample quotes, 8 discovered operators
├── discovery/
│ ├── faa-scraper.ts # FAA Part 135 registry HTML scraper
│ └── pipeline.ts # Scrape → store → email orchestration
├── email/
│ ├── resend.ts # Resend API client with stub mode
│ └── templates.ts # Branded HTML email templates
├── outreach/
│ └── engine.ts # Matching algorithm, RFQ generation, Resend delivery
└── payments/
├── config.ts # Mode detection, fee calculation
├── stripe.ts # Stripe client
├── service.ts # Checkout, fulfillment, refunds, Connect, webhook handling
└── __tests__/ # Vitest suite
Database Schema
Fifteen tables in Postgres:
| Table | Purpose |
|---|
users | App profile for every account (customer, operator, admin): role, phone, auth_id link to Neon Auth, is_demo. password_hash is used only by the development sign-in. |
operators | Linked to a user. Company name, certificate, approval status, contact preferences, market/fleet/safety profile for matching. |
aircraft | Operator fleet inventory. Tail number, type, capacity, range, year, serial/manufacturer/model, last FAA registry record (faa_record JSON, faa_checked_at). |
aircraft_photos | Photos per aircraft: JPEG/PNG/WebP bytes and thumbnail (BYTEA), position (0 = cover), dimensions, caption. |
booking_requests | Customer trip requests. Status lifecycle: open → quoted → booked → completed (or cancelled). |
booking_legs | Individual flight legs within a request. Origin, destination, date, time. |
quotes | Operator price submissions. Linked to request + operator + optional aircraft. Status: pending → accepted/rejected/withdrawn. |
outreach_log | Every RFQ dispatched to an operator. Method, match score, RFQ content, delivery status. Unique on (request_id, operator_id). |
discovered_operators | FAA-scraped operators pending outreach. Certificate number (unique), contact info, discovery status. |
payments | One row per checkout attempt. Amount, platform fee, operator payout, refunded total, Stripe session and PaymentIntent IDs, status. |
refunds | Ledger of refunds issued from the app. |
payment_events | Stripe webhook event IDs that have been processed, used for idempotency. |
trip_shares | Private trip sheet links for booked charters. Revocable; expire 30 days after the last leg. |
operator_staff | An operator's staff roster: contact details, alert channels and which events each person receives. |
staff_notifications | One row per staff alert per channel. Unique on (staff_id, event_key, channel) so alerts are never duplicated. |
The operators table also stores the Stripe Connect account ID, capability flags, and an optional fee override.
Database access
src/lib/db/index.ts picks the database:
DATABASE_URL | Database |
|---|
| Set | Postgres via pg (production: Neon's pooled connection string, injected by the Vercel integration) |
| Unset, development | Embedded PGlite (Postgres compiled to WASM) in data/pglite. Nothing to install. |
| Unset, production | Startup error |
- Schema (
schema.ts) is applied on the first query after each cold start. Every statement is IF NOT EXISTS, and an advisory lock stops concurrent cold starts from colliding. Schema changes must be additive and idempotent.
- Queries use
? placeholders, which are rewritten to $1, $2, …. Do not put a literal ? in SQL text.
- Types:
COUNT/SUM/BIGINT values come back as JS numbers. Timestamps (TIMESTAMPTZ) come back as ISO 8601 strings. Money is stored in cents as BIGINT.
- Payment fulfillment locks the booking request row (
SELECT … FOR UPDATE). Stripe webhooks for the same request on different serverless instances then run one at a time instead of deadlocking or double-booking.
Getting Started
git clone https://github.com/Add-Homonym/bespoke.flights.git
cd bespoke.flights
npm install
cp .env.example .env.local # fill in values
npm run seed # loads test data into the local PGlite database
npm run dev # http://localhost:3000
npm test # Vitest suite (in-process PGlite)
No database setup is needed locally. To develop against Neon instead, pull the project's env vars (vercel env pull .env.local). Prefer a Neon development branch over production. The seed script refuses to run when DATABASE_URL is set unless you pass SEED_DATABASE=yes, because it creates accounts with a known password.
To run the tests against a real Postgres server (tables are truncated):
TEST_DATABASE_URL=postgres://… npm run test:pg
Test Accounts
Created by npm run seed locally, or automatically in test mode. All use password password123:
Environment Variables
| Variable | Required | Description |
|---|
NEON_AUTH_BASE_URL | Production | Neon Auth endpoint (Neon console → Auth). Leave empty locally to use bcrypt accounts and a JWT cookie instead. |
NEON_AUTH_COOKIE_SECRET | Production | Signs Neon Auth session cookies (32+ random characters). |
JWT_SECRET | Development | Signs the development session cookie. Must be 16+ characters and not change-me; without it, development uses a random per-process key (sessions end on restart) and production refuses to sign. |
RESEND_API_KEY | No | Resend API key. Without it, emails log to stdout. |
INBOUND_EMAIL_SECRET | No | Bearer token for POST /api/webhooks/inbound-email. When set, RFQ emails offer reply-by-email quoting. |
EMAIL_REPLY_DOMAIN | No | Domain for quotes+<token>@ reply addresses. Defaults to the domain of EMAIL_FROM. |
EMAIL_FROM | No | Verified sender address (default: [email protected]) |
CRON_SECRET | Production | Secures the /api/cron/weekly-discovery and /api/cron/daily-lifecycle endpoints |
STRIPE_SECRET_KEY | Production | Stripe secret key. Without it, payments run in stub mode (development) or are disabled (production). |
STRIPE_WEBHOOK_SECRET | Production | Signing secret for the platform webhook endpoint |
STRIPE_CONNECT_WEBHOOK_SECRET | Production | Signing secret for the connected-accounts webhook endpoint |
PLATFORM_FEE_BPS | No | Fallback platform commission in basis points (default 500 = 5%) until set at /admin/settings |
APP_URL | Production | Public base URL for Stripe redirect URLs and links in emails and texts. In production the request's Host header is never used; without APP_URL the app falls back to Vercel's and otherwise fails the request. |
Deployment (Vercel)
Vercel is the only host. netlify.toml tells Netlify to skip every build of this repository; Netlify's dashboard connection can also be removed.
1. Database: Neon through the Vercel Marketplace
- In the Vercel dashboard, open the bespoke.flights project → Storage → Create Database → Neon (Serverless Postgres).
- Choose a region close to the project's function region, then Connect it to the project for Production, Preview and Development.
- The integration adds
DATABASE_URL (pooled) and related PG*/POSTGRES_* variables. The app only reads DATABASE_URL.
- Redeploy. Tables are created on the first request.
Optional: enable Neon's preview-branch option in the integration so each preview deployment gets its own database branch instead of sharing production data.
2. Other environment variables
Set NEON_AUTH_BASE_URL, NEON_AUTH_COOKIE_SECRET, CRON_SECRET (required for the scheduled discovery run), APP_URL, and the Stripe, Resend and Twilio variables from the table above.
3. Deploy
vercel deploy
The cron schedules in vercel.json run the discovery pipeline every Monday at 18:00 UTC (8:00 AM HST) and the quote/trip lifecycle job daily at 10:00 UTC. Vercel Cron requires a Pro plan.
To test the cron endpoint locally (set CRON_SECRET in .env.local):
curl -X POST http://localhost:3000/api/cron/weekly-discovery \
-H "Authorization: Bearer $CRON_SECRET" \
-H "Content-Type: application/json" \
-d '{"states": ["HI"], "emailsPerRun": 5}'
Pending / Future Work
- SMS delivery status — Twilio status callbacks are not tracked; a text counts as sent once Twilio accepts it.
- Resend webhooks — track email bounces and mark discovered operators as
bounced automatically.
- Secondary email discovery — the FAA registry doesn't publish emails. A future enrichment step (website scraping or data API) could automate email collection for
no_email operators.
- AI phone outreach — the contact method enum can be extended with
phone for Bland.ai / Vapi voice agent integration.
- Operator invoicing / 1099-K reporting — Stripe Connect produces tax forms for Express accounts. Travelers have a printable receipt; operators have no in-app invoice document yet.
- Deposits and balance payments — the full quote amount is charged at booking. Split payments (deposit now, balance before departure) are not supported.
