Deposit-gated booking architecture

1. Stage 01

   Booking entry points

   Three independent paths by which an appointment can arrive, only one of which the fix could touch directly.

   • Landing-page widget · Source · Browser — A framework-free widget served by the worker itself and mounted with a single async script tag, calling only the worker’s availability and booking routes. → Availability + booking (patient picks a slot)
   • AI agent booking node · AI · CRM Conversation AI — A flow-builder conversation agent over messaging and web chat that books inside dedicated booking nodes. → Calendar auto-confirm off (books with no status set)
   • CRM calendar link · Source · CRM — The third arriving path — the CRM’s own booking link — named alongside the agent and the landing page in the root-cause analysis. → Calendar auto-confirm off (books with no status set)

2. Stage 02

   Booking worker

   The stateless edge service that reads availability, writes the appointment, and holds no state of its own.

   • Cloudflare booking worker · API / service · Cloudflare Workers — A small TypeScript worker split into a router, a CRM API layer, typed env, a CORS module, a validator and the widget source, exposing eight routes. → Availability + booking (routes), Duplicate-booking collapse (keyed route)
   • Availability + booking · API / service · Worker — One route returns free slots for a window — defaulting to a fortnight and hard-capped at the CRM’s own free-slots ceiling — and another validates the body, upserts the contact and creates the appointment, returning the appointment and contact ids with the status. → Booking validator (every request), Origin + key gates (origin-gated)
   • Booking validator · Guard · Worker — A discriminated-result validator enforcing a minimum notice, a forward cap, name and phone length limits and email and phone patterns. → Slot written unconfirmed (validation passes)
   • Origin + key gates · Guard · Worker — An exact-match origin allow-list on the public-facing routes, and a shared secret protecting the four server-to-server routes, which are deliberately not origin-gated because they are called from CRM workflows.
   • Naive-local → UTC · Guard · Worker — The CRM’s appointment list returns naive local wall-times with no offset while the appointment write parses bare strings as UTC. → Availability + booking (every time comparison or write)
   • Duplicate-booking collapse · API / service · Worker — A keyed route that collapses duplicate future bookings for a contact.

3. Stage 03

   Appointment state model

   Reserved, confirmed, released — and what "confirmed" is now allowed to mean.

   • Slot written unconfirmed · Calendar · CRM — The booking write was changed from confirmed to a reserved status, so the slot is held against other bookers the moment the patient books while the diary shows it as unconfirmed. → Three-state model, 24-hour hold (hold starts at booking), Deposit link + chase (reserved-status trigger fires)
   • Calendar auto-confirm off · Calendar · CRM — The calendar’s auto-confirm setting was flipped off by a direct update, and the thank-you copy rewritten from "your assessment is confirmed" to "your assessment time is reserved". → Slot written unconfirmed (auto-confirm off → default is reserved)
   • Three-state model · Data store · CRM — Reserved — slot blocked, deposit unpaid, written by the booking route and by the calendar default. Confirmed — deposit paid, written only by the promote endpoint. Released — the record is deleted and the slot returns to the diary, written only by the release endpoint.
   • 24-hour hold · Wait · CRM workflow — An unpaid reservation holds the slot for 24 hours, then it is released. → Unpaid slot guard (T+24h and still unpaid)

4. Stage 04

   Deposit chase

   A 24-hour ladder, its ordering, and the guards that stop a message breaking on a real merge value.

   • Deposit link + chase · Workflow · CRM — Triggered on a reserved appointment on the assessment calendar: it tags link-sent, sends the deposit link by SMS and email, then runs a ladder of paid-checks and reminders. → Two-minute ordering wait (so the link lands last)
   • Recompressed to 24h · Message · SMS + email — The ladder was recompressed from a 72-hour shape to a 24-hour one: deposit link at T+0, reminder at T+3h, reminder plus the deposit-outstanding staff alert at T+12h, final reminder at T+22h, release at T+24h. → Four paid-check gates (at each rung), Prefill redirect (every rung carries the short link), Rewritten staff alerts (deposit-outstanding alert at T+12h)
   • Four paid-check gates · Decision · CRM — Four identical gates test whether the paid tag is present; the paid branch is a self-removal from the workflow. → Deposit link + chase (paid tag present → self-exit), Unpaid slot guard (final paid-check fails)
   • Single-segment SMS guard · Guard · Build tooling — Two independent implementations: an inline guard inside the migration script that aborts before any network call, and a full checker that computes segment counts for both encodings. → Recompressed to 24h (every body, before any write)
   • Two-minute ordering wait · Wait · CRM — A collision fix made after a lead received four texts and two emails inside one minute. → Recompressed to 24h
   • Agent stops saying confirmed · AI · CRM Conversation AI — The agent’s end messages were replaced with reserved wording and its booking-node instructions rewritten. → AI agent booking node (never claim confirmed)

5. Stage 05

   Payment

   The prefill redirect, the deposit link, and the handler that runs when money lands.

   • Prefill redirect · API / service · Worker — An unauthenticated redirect that looks the contact up and forwards to the deposit payment link with first name, last name and email prefilled. → Deposit payment link (redirect with prefill)
   • Deposit payment link · Payment · CRM-hosted, Stripe-backed — A CRM-hosted payment link backed by Stripe, moved from test to live mode on the payment link’s own edit screen. → Deposit paid handler (payment received, filtered to the deposit product)
   • Deposit paid handler · Workflow · CRM — Triggered by a payment event filtered to the deposit product: a leading gate no-ops if the paid tag is already present, otherwise it tags paid, calls the promote webhook, sends the confirmation, raises the staff alert, writes the amount onto the card and advances it. → Deposit paid handler (paid tag already present → dead-end no-op), Mark-paid endpoint (keyed promote webhook), Four paid-check gates (the paid tag ends the chase)

6. Stage 06

   Promotion to confirmed

   The keyed endpoint that resolves an appointment from a contact, and why its position in the step list is the design.

   • Mark-paid endpoint · API / service · Worker — A keyed POST that resolves the appointment FROM the contact — selecting appointments on the clinic calendar still reserved, earliest first — and promotes the first to confirmed. → Origin + key gates (wrong key refused), State-precondition idempotency (reserved-only precondition), Three-state model (reserved → confirmed), Deposit-paid staff alert (after the patient confirmation), Live endpoint proofs (confirmed, then no-op, then refused)
   • State-precondition idempotency · Guard · Worker — There is no token, nonce or dedupe table: both new endpoints select only appointments still in the reserved status, so a repeat call finds nothing and returns a no-op.
   • Promote before telling · Guard · CRM — The promote webhook is placed immediately after the paid tag and before the confirmation messages. → Deposit paid handler (promote before the patient is told)
   • Deposit-paid staff alert · Staff alert · CRM email — A new internal notification spliced between the patient confirmation email and the card step, addressed to the clinic inbox plus a second named staff recipient.

7. Stage 07

   Unpaid release

   Freeing a held slot without ever telling a patient they cancelled something.

   • Unpaid slot guard · Workflow · CRM — Rebuilt from an email asking a human to do something into the actual enforcement arm: the release webhook is inserted as step zero, made the parent of the previous root step. → Release endpoint (step zero, before any card lookup), Rewritten staff alerts (slot-released alert)
   • Release endpoint · API / service · Worker — A keyed POST that selects appointments on the clinic calendar still reserved AND strictly in the future, deletes every match, and returns the released ids or a no-op. → Origin + key gates (keyed server-to-server), Late-payment race guard (reserved-only, strictly future), Delete, never cancel (delete the record), Live endpoint proofs (refused a paid booking, released a reserved one)
   • Delete, never cancel · Guard · Worker — Deletion rather than cancellation, deliberately: deleting removes the appointment’s own workflow enrolments and fires no cancellation event, live-proven. → Three-state model (record removed, slot back in the diary)
   • Late-payment race guard · Guard · Worker — Only reserved appointments are eligible, so a deposit landing in the same minute as the release — already promoted to confirmed — can never have its slot deleted underneath it. → Delete, never cancel (still reserved and still future)
   • Rewritten staff alerts · Staff alert · CRM email — The outstanding alert was retimed and rewritten to say the reservation is released automatically at 24 hours, ending "call them first if you would rather keep the slot held"; the released alert reports what the automation did.

8. Stage 08

   The cutover

   Four repointed triggers in one atomic pass, and the platform limit that forced it to be atomic.

   • Four triggers, one cutover · Scheduled job · CRM — All four triggers had filtered on the assessment calendar plus a confirmed status; all four were repointed to the reserved status and renamed to say so. → Deposit link + chase (repointed first — patient-visible), Duplicate-booking collapse (widened to see reserved bookings), Nothing left on confirmed (nothing left keyed on confirmed), Live endpoint proofs (verify the final trigger state)
   • Nothing left on confirmed · Guard · CRM — The cutover deliberately leaves no trigger keyed on the confirmed status at all. → Three-state model (one writer per state)
   • Trigger-write platform limit · Guard · CRM API — The full-document write with trigger-change flags returns success and does nothing; creating a trigger by POST returns an id but produces an orphan that never attaches. → Abandoned phased route (document write silently refuses)
   • Abandoned phased route · Report · Build tooling — A phased migration was written first — clone each trigger verbatim, swap only the status value, run both live so the migration is order-independent, remove the old one just before promotion goes live. → Four triggers, one cutover (phased route abandoned → one atomic pass)
   • Migration safety harness · Guard · Build tooling — Present in every migration script: dry-run by default, a token-expiry pre-check, rate-limiting between calls, a JSON snapshot of pre-change state into a dated backups folder, a per-workflow abort if the expected shape is absent, and a non-zero exit on any failed verification. → Four triggers, one cutover (dry-run, backup, verify from a fresh read)

9. Stage 09

   Proof & handover

   Live endpoint proofs, an account-wide alert inventory, and a handbook that grades its own claims.

   • Live endpoint proofs · Report · Live account — A proof section listing five items, captured as raw responses rather than narrative claims: a real reservation through the widget with its tags landing within seconds, promote then a repeat no-op then a wrong-key refusal, a release that refused a paid booking and then deleted a reserved one, the agent path defaulting to reserved, and the final trigger state. → Owner handbook (proven behaviour becomes documented behaviour)
   • Recorded as unproven · Report · Handover — What was left open, written down rather than glossed: the release is verified at the endpoint but no contact has yet walked the whole ladder, and the new deposit-paid alert was saved but had not fired live. → Owner handbook (unverified claims generalised, never guessed)
   • Account alert inventory · Report · CRM (read-only) — All 25 workflows exported and scanned against live data in one pass to verify four staff-alert rails end to end — lead in, booked, deposit paid, human takeover — and to add the second recipient. → Deposit-paid staff alert (four alert rails verified end to end), Recorded as unproven (a missing alert path found and escalated)
   • Owner handbook · Report · Deliverable — A self-contained, offline-verified page plus a PDF printed from it with page breaks verified, superseding an earlier guide written before this model existed.

Platforms · GoHighLevel · Cloudflare Workers · Conversation AI · Stripe