English

bespoke.flights

Book bespoke private charter flights. Multi-leg itineraries, competitive quotes from certified operators.

Translation pending

LifestyleTypeScript · JavaScriptGitHub @Add-HomonymOnlineOwner unconfirmed

Visit project GitHub

Have you tried it? One tap is enough. No sign-in needed.

Availability: Online; 30-day uptime 100%
Latest code update: Oct 23; Active repository
Latest version: None
Contributors: 3; Forks 0
Listed on nomorevibe: Oct 12; Repository created March 2026

Languages

TypeScript 95.5%
JavaScript 3.3%
CSS 1.2%

Updates0 updates

All

No updates detected yet. GitHub releases will appear here.

Comments

Newest first

···

GitHub issue delivery settings

Checking sign-in status.

Loading comments.

bespoke.flights — nomorevibe

Introduction

A booking engine for private charter flights

Translation pending

Taken from the repository README

README

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:

Email	Role	Notes
`[email protected]`	Admin	Full platform access
`[email protected]`	Customer	Has a 3-leg east coast request with 2 quotes
`[email protected]`	Customer	Has a LAX↔HNL request, no quotes yet
`[email protected]`	Operator	Elite Air Charter — approved, full profile, G650 + Citation X
`[email protected]`	Operator	SkyBridge Aviation — approved, Global 7500 + Phenom 300E
`[email protected]`	Operator	Pacific Wings — approved, Hawaii specialist
`[email protected]`	Operator	Westside Jets — pending approval, no profile

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.

Read the full README ↗

README

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

Quoting by replying to the RFQ email

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

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

Cancelling a paid booking

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

Changing a booked trip

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.

Empty legs

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.

Messaging

Platform fee

Refunds and disputes

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)

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:

Email	Role	Notes
`[email protected]`	Admin	Full platform access
`[email protected]`	Customer	Has a 3-leg east coast request with 2 quotes
`[email protected]`	Customer	Has a LAX↔HNL request, no quotes yet
`[email protected]`	Operator	Elite Air Charter — approved, full profile, G650 + Citation X
`[email protected]`	Operator	SkyBridge Aviation — approved, Global 7500 + Phenom 300E
`[email protected]`	Operator	Pacific Wings — approved, Hawaii specialist
`[email protected]`	Operator	Westside Jets — pending approval, no profile

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.

Read the full README ↗

TripDetails

src/lib/trip-format.ts

Staff alerts at /operator/team. Add up to 50 staff, each with an email and/or a mobile number. Choose per person:

Channels: email and/or text.
Events: charter booked, charter cancelled, and new request to quote.

Alerts go out automatically when a payment completes, when a booking is cancelled (by the customer or a full refund) and when the matching engine sends the company an RFQ. Booking alerts include the private trip sheet link. Each person gets each alert once per channel: redelivered webhooks do not duplicate it, and failed sends are retried on the next trigger (staff_notifications table). Send test checks a person's setup.

Staff board link: a private, read-only /board/<token> URL of the company board for dispatch screens or staff without an account. It can be replaced or turned off at any time. 8b. Autopilot at /operator/autopilot, a cockpit-style console. When engaged, every request matched to the operator gets a drafted quote (src/lib/quotes/autopilot.ts): the smallest aircraft that seats the group and covers the longest leg, leg hours from distance and cruise speed, positioning from and back to the home base, then the operator's margin, fuel surcharge, daily minimum, crew overnights, landing per leg, catering per guest per leg, excise tax and segment fees through the quote worksheet. Drafts are stored in quote_drafts with notes for the reviewer (no rate on file, group larger than the fleet, range short of a leg) and are never visible to travelers. The console streams incoming requests every 8 seconds with each one's draft or quote; Review opens the inbound form prefilled, where a staffer adjusts and presses Approve and submit quote. Requests can also be drafted on demand with Draft with Autopilot. Engaging Autopilot drafts the requests already waiting. Routes: GET/POST/DELETE /api/booking-requests/[id]/draft. Learning (src/lib/quotes/learning.ts, on by default, LEARN switch on the console): every quote submitted or revised with the worksheet updates weighted averages of the operator's margin, fuel surcharge, daily minimum, crew overnight, landing per leg, catering per guest per leg, tax and segment fee; per aircraft, the hourly rate and how entered flight times compare with the distance estimate; and how far staff move the final price from the worksheet total. Drafts use learned values once they exist (shown as LRN on each instrument and listed on the draft), an aircraft with no rate on file takes the rate staff used, and open drafts are redrafted after each submission. Stored in autopilot_learning; RESET on the console (DELETE /api/operator/autopilot/learning) returns to the setpoints.

VERCEL_PROJECT_PRODUCTION_URL

bespoke.flights

Languages

Updates0 updates

Comments

Trending in Lifestyle

bespoke.flights

Languages

Updates0 updates

Comments

Trending in Lifestyle

Do you operate this project?

Introduction

README

bespoke.flights

How It Works

Who can see what

Customer Workflow

Operator Workflow

Admin Workflow

Automatic Outreach System

Matching Algorithm

Market Classification

RFQ Delivery

Quoting by replying to the RFQ email

Operator Discovery Pipeline

How It Works

Discovery Statuses

Admin Discovery UI

Payments

Flow

Receipts

Cancelling a paid booking

Changing a booked trip

Empty legs

Messaging

Platform fee

Refunds and disputes

Payment statuses

Modes

Test mode

Stripe setup

Quote lifecycle

Email System

Project Structure

Database Schema

Database access

Getting Started

Test Accounts

Environment Variables

Deployment (Vercel)

1. Database: Neon through the Vercel Marketplace

2. Other environment variables

3. Deploy

Pending / Future Work

README

README

bespoke.flights

How It Works

Who can see what

Customer Workflow

Operator Workflow

Admin Workflow

Automatic Outreach System

Matching Algorithm

Market Classification

RFQ Delivery

Quoting by replying to the RFQ email

Operator Discovery Pipeline

How It Works

Discovery Statuses

Admin Discovery UI

Payments

Flow

Receipts

Cancelling a paid booking

Changing a booked trip

Empty legs

Messaging

Platform fee

Refunds and disputes