DEV Community: Nitin Doyal

Recurring Appointments Done Right: RRULE, Exceptions and the Four Cases That Break a Naive Rule

Nitin Doyal — Sat, 10 Oct 2026 17:38:45 +0000

"Repeat every 7 days" is one line of code and about four months of support tickets.

Recurring bookings look like a scheduling feature and behave like a data-integrity feature. The moment a customer says "actually, cancel just the 14th one", you are no longer computing dates — you are maintaining a set of exceptions against a rule, and the naive model cannot express that.

Here is the shape that survives.

The four cases that break the naive rule

1. The occurrence that doesn't exist. "Every second Tuesday" or "the last Friday of the month" has no occurrence in some months. A rule engine that silently produces nothing looks fine until a customer complains that their March appointment vanished. You need an explicit answer for months with no occurrence: skip, shift to the nearest day, or hold the last one. Pick deliberately and tell the customer which one you picked.

2. The exception. A customer cancels the 14th. If you store only the rule, the 14th comes back next cycle. If you delete the rule and re-create it, you lose the history of the earlier instances. You need both: the rule, and a list of instance-level overrides.

3. Retroactive changes. Staff changes their Tuesday shift. Do the next twelve Tuesdays move? Do the past ones? Past instances should never move — they are records of what happened. Future unmodified instances move; instances with their own override stay put. This is exactly the "this / this and following / all" semantics, and it is much easier if the distinction is structural rather than a flag you retrofit.

4. Timezone and DST. "10:00 every Monday" is a wall-clock statement, not an instant. A clinic in Jodhpur doesn't shift, but a customer travelling, a remote consultation, or a DST-observing location does. Store the series' timezone, compute instants from wall-clock rules, and never store a raw UTC instant as the rule.

Model: series, rule, instances, overrides

series {
  id            uuid
  service_id    uuid
  staff_id      uuid
  timezone      text          -- IANA, e.g. 'Asia/Kolkata'
  rrule         text          -- the recurrence rule
  starts_on     date
  ends_on       date nullable
  status        active|ended
}

series_instance {
  id            uuid
  series_id     uuid
  starts_at     timestamptz   -- materialised instant
  ends_at       timestamptz
  status        scheduled|booked|cancelled|completed
  source        rule|override
}

Two decisions do most of the work here.

Materialise instances ahead. Generate the next N occurrences (say 26 weeks) at creation time rather than computing them on read. Queries get simple, availability checks become ordinary range queries, and the exclusion constraint that prevents double-booking applies to instances exactly as it does to one-off bookings.

Override, never mutate. Cancelling one instance flips its status. Moving one instance updates that row and marks source = 'override'. The rule stays authoritative for everything else.

"This / this and following / all"

This is the interaction design that users judge you on. Implement it as an explicit operation rather than a UI-only concept:

This occurrence — update one instance row
This and following — end the current series at the previous occurrence, spawn a new series starting at this one with the new rule
Entire series — update the series and regenerate all unmodified future instances; leave overridden ones alone

The "this and following" case is the one people forget. It is also the one that makes an audit trail possible, because you never rewrite history — you close one series and open another.

Availability has to consider the rule, not just the slots

When a customer picks a time for a new series, you are not checking one slot. You are checking whether the whole pattern is viable: staff shifts must cover every generated instance, service duration must fit, and the resource must be free each time.

Two practical rules:

Validate all generated instances in one pass, and report which ones fail rather than rejecting the series wholesale. "Tuesday 10:00 is unavailable on 3 of the 26 dates — here they are" is a far better message than "invalid schedule".
Reserve the first instance immediately, then create the series in the same transaction. A series that exists with no reserved opening is a booking you cannot honour.

Cancelling a series

"Cancel the rest" should cancel future unscheduled instances and leave completed ones intact. If the customer has already been charged or has consumed sessions, you are in billing territory — record the cancellation against the series, not by deleting rows.

Also decide what happens to a cancelled series that is later reactivated. Restarting it as a new series is almost always simpler than resurrecting the old one, because the old one's instance set no longer matches its rule.

Testing the boring way

The tests that catch real bugs:

A rule with no occurrence in a given month (last Friday of February)
Cancel one instance, run the generator again, assert it does not come back
"This and following" — assert the earlier instances keep their original times
A DST transition inside the range — assert wall-clock time is preserved
Two concurrent bookings for the same instance — assert exactly one wins

If you only test the happy path, you will ship the version that works until a customer needs to cancel one date.

The summary

Recurring bookings are a small rules engine with an exception list, not a date loop. Store the rule and the timezone, materialise instances ahead, express every change as an override, and keep "this / this and following / all" as three distinct operations with different data effects.

If you would rather not maintain any of it, SWIQ handles recurring bookings, overrides and availability for Indian clinics and salons — see it on a free demo. Our guide to appointment booking software with WhatsApp covers how confirmations behave for series, and the clinic booking system guide walks through multi-provider setup.

Reminder Delivery That Doesn't Spam: Idempotency Keys, Quiet Hours and Honest Opt-Outs

Nitin Doyal — Sat, 10 Oct 2026 16:17:00 +0000

Every team that adds appointment reminders eventually ships the same bug: a patient gets the same message four times, at 11 pm, on a number that replied STOP two weeks ago.

It is not a difficult problem to reason about. It is a difficult problem to keep reasoning about, because reminders sit at the intersection of four systems — your scheduler, your template provider, your delivery queue and a customer's stated preferences — and each of them has a different idea of "should this be sent".

Here is the shape of a reminder pipeline that survives contact with production.

1. Generate reminders from an immutable schedule

The first decision: when is a reminder created?

Not when you send it — when you decide it should exist. Create reminder records at booking time:

reminder {
  id              uuid
  booking_id      uuid
  send_at         timestamptz    -- instant, computed from the business zone
  template        enum
  channel         enum
  status          pending|sent|cancelled|skipped
  idempotency_key text unique
  attempt_count   int
}

Storing them means the booking is the source of truth, not the cron output. Cancel the booking → cancel the reminder rows. Reschedule → regenerate from the new anchor. No orphaned messages, no reminders for appointments that no longer exist.

The idempotency_key is the load-bearing field. Construct it deterministically:

f"{booking_id}:{template}:{send_at_epoch}"

Because it is derived rather than random, any duplicate generation path — a retried job, a re-run after a deploy, a manual backfill — produces the same key and the unique index rejects it. This single constraint eliminates an entire category of "sent twice" reports.

2. Send through a queue, never inline

The API request that creates a booking must never call WhatsApp. It writes the reminder rows and returns.

A worker picks up status = pending AND send_at <= now() and attempts delivery. Why this matters:

Provider outages don't fail the booking
Retries are explicit and bounded
You can drain the queue in order, or prioritise same-day reminders when a provider is slow
Rate limits become a queue-depth problem, not an error budget problem

Wrap each attempt in a try/catch with a bounded retry policy — say 3 attempts over 15 minutes with exponential backoff — then mark the row skipped with the provider error. A permanently failing number should not be retried forever, and you need the terminal state to report on it.

3. Make the worker idempotent even if the provider isn't

Some providers deduplicate; most do not. If your worker crashes after the provider accepts the message but before you mark it sent, a naive retry sends it twice.

Two mitigations, use both:

Pass the idempotency key to the provider if it supports one. Many WhatsApp and SMS APIs accept a client reference.
Mark before or after, with a state machine. Move pending → sending before the call and sending → sent after. On restart, rows stuck in sending are reconciled against provider delivery logs (most expose a lookup by client reference) rather than blindly retried.

Blindly retrying from sending is how you get duplicate messages on the day your deploy goes wrong.

4. Quiet hours are a first-class rule, not a config flag

A reminder computed for 9 am at the clinic might land at 11 pm for a customer in another timezone, or a re-run might push a batch into the night.

Encode quiet hours explicitly:

Compute send_at in the recipient's effective timezone, not the business's — unless they are the same, which you should establish at booking.
Clamp, don't drop. If a message would fall inside quiet hours, move it to the start of the next allowed window rather than discarding it. A slightly late reminder beats no reminder.
Never clamp past the appointment. If shifting would put the message after the start time, send it immediately (if allowed) or mark it skipped with a reason.

Also decide what happens on the day of the appointment: a "you're next" message at 06:00 is worse than no message.

5. Opt-out is a global kill switch, checked at send time

The single most expensive mistake is checking consent only at enqueue time.

Consent can change between send_at being computed and the worker firing — someone replies STOP, or unsubscribes from settings, while60 messages sit in the queue. So check at send time:

if recipient.opted_out:            status = 'skipped', reason='opted_out'
elif recipient.quiet_now():        reschedule to next window
elif channel == 'whatsapp' && !opt_in_confirmed: status='skipped', reason='no_opt_in'
else:                              send

Three things to keep straight:

Transactional vs marketing. A booking confirmation may be permitted where a promotional offer is not. Tag every reminder with its category and apply the right rule.
Channel-level opt-out. Unsubscribing from WhatsApp should not silently disable SMS for security-style messages — unless that's what they asked for.
Record the decision. skipped with a reason is a report. No row is an invisible failure.

Compliance-wise: for WhatsApp Business, opt-in must be collected before the first message, and every template message needs a visible way out. Check the current WhatsApp Business Messaging Policy before you decide what counts as transactional.

6. Template changes are a deploy, not an edit

Reminder copy lives in provider-approved templates with their own approval lifecycle. Treat a template change like a code change:

Version templates. A reminder row should record which version it intended to use.
Never mutate a template in place while messages are pending — you will get a mixed batch.
Handle rejection. A template that fails review should fail loudly, not silently skip messages for a week.

7. What to measure

Four numbers tell you whether the pipeline is healthy:

Delivery rate — accepted by provider ÷ attempted
Duplicate rate — should be structurally zero; if it isn't, your idempotency boundary is wrong
Skipped by reason — opted-out, quiet hours, invalid number, template rejected. Each one is an actionable bucket
Reminder → show-up correlation — the actual point of the exercise

Watch the skipped buckets weekly. A spike in invalid_number means your capture form has a bug; a spike in quiet_hours means your time window is wrong for your customers.

The summary

Reminders are not "send a text an hour before". They are a durable job system with a consent check, a timezone rule, a uniqueness constraint and a terminal state for every message. Generate early, enqueue, check consent at send time, idempotency-key everything, and record why each message didn't go out.

If you would rather not maintain any of it, SWIQ ships booking confirmations, day-before reminders and live queue notifications for Indian clinics and salons — see it on a free demo.

For the operational side, our guide to appointment no-show management covers timing and messaging strategy, and this overview of appointment booking software with WhatsApp compares what platforms handle for you.

Shipping an Appointment Booking Flow That Survives Patchy Networks

Nitin Doyal — Sat, 10 Oct 2026 13:22:28 +0000

Most appointment booking demos are filmed on office wifi. The production traffic is not.

If you build booking flows for small businesses — clinics, salons, service counters — the network your customers are on is the one that matters: a ₹7,000 Android phone, three bars of 4G that drop to Edge inside a concrete waiting room, and a user who will abandon the form at the first spinner that outlives their patience.

This is a field report on the things that actually break in an appointment booking flow, and what to do about each one.

1. The link has to open, not install

The first requirement is not technical, it's commercial: there is no app to download.

A customer scanning a QR code at a salon door, or tapping a booking link in an Instagram bio, has decided to give you about eight seconds. An app-install interstitial converts that intent into a bounce. A web page that renders something useful in under two seconds does not.

So the constraints are:

Server-render the first paint. Do not ship an empty <div id="root"> and hydrate your way to a booking form.
Put the service list and the first available slots in the initial HTML, not behind a client fetch.
Defer everything that is not the booking decision: analytics, chat widgets, review widgets, fonts you don't need for the first screen.

Treat the booking page like a landing page, because that is exactly what it is.

2. Design for the request that never arrives

The failure you must handle is not a 500. It's a request that hangs for 30 seconds and then times out — and the user taps Confirm four more times.

Four things save you here.

Idempotency keys. Generate a key client-side per booking attempt and send it with every retry. The server stores the key with the created booking and returns the original result on replay. Without it you get four bookings for one haircut, and the fourth one is the version the staff sees.

An explicit pending state. "Confirming your booking…" is honest. A button that silently disables is not — users tap disabled buttons and assume the app is broken.

A single source of truth after success. Once the server confirms, the client must show the server's booking object, not its local optimism. Local state and server state drifting apart is how a customer turns up for an appointment that never existed.

A recoverable pending queue. If the network dies mid-submit, stash the intent in IndexedDB with its idempotency key and retry when connectivity returns. On reconnect, the user should see "we still have your booking pending — retry?" rather than a cleared form.

Test it the cheap way: open DevTools, set the network to Offline halfway through submission, and watch what your app does. If the answer is "nothing visible," you have found your first bug.

3. Backoff that respects the user

Naive retry loops are a self-inflicted DDoS. Three rules:

Exponential backoff with jitter. 1s, 2s, 4s, 8s — plus random jitter so a thousand clients don't retry in lockstep after a blip.
Cap the attempts and fail loudly. After four attempts, show a real error with a phone number. Silence after a long retry chain is the worst possible outcome.
Never retry a 4xx. A validation error will fail identically forever. Retrying it burns the user's battery and your API quota.

Same logic applies on the outbound side. If you push confirmations to WhatsApp or SMS and the provider returns a 429, back off — do not retry immediately and get your number throttled.

4. Notifications are a delivery problem, not a template problem

The booking confirmation is easy. The reminder that prevents a no-show is where systems fail, because it is a scheduled job that must fire at a specific local time for a specific person.

Things that bite:

Store the timezone, not just the offset. The offset changes; the timezone name does not. Store Asia/Kolkata (or the business's zone) and convert at send time.
Schedule in the server's clock, not the customer's browser. A phone clock that's six minutes fast should not decide whether a reminder goes out.
Make sends idempotent too. If the reminder worker restarts mid-run, you do not want to send the same message twice.
Log the provider's message ID. When a customer says "I never got the reminder," you need to distinguish not sent, sent but not delivered, and delivered to a phone that was off.

A useful rule: the confirmation proves the booking happened; the reminder is what makes the booking happen twice (once on the calendar, once in the room).

5. QR codes are entry points, not decoration

For walk-in businesses, the QR code on the door is the front door. That has a couple of implications:

The QR must resolve to a URL that works without a session, an app, or a login.
It should deep-link as far as it can — straight to the service list, not the homepage.
Print it large, with a fallback short URL for people who won't scan.
Give it a landing state for after hours: "bookings open at 10 am" beats a broken page.

Small thing, big effect: make sure the URL survives a WhatsApp message unfurl and a Gmail preview, since that is where the link often travels next.

6. Measure the thing your user feels

Lighthouse on desktop wifi is a comforting fiction. Measure the real path:

INP (Interaction to Next Paint) on the service picker — this is the actual "is it laggy?" metric.
LCP on the booking page — is the first slot visible without scrolling and without a jank?
Field data over lab data. CrUX or your own RUM, segmented by device, not your laptop's throttled simulation.

Watch for the classic pattern: the first visit is fine because it's warm, and the second visit — after the service worker serves a stale shell — is where it falls apart. Test your cold-cache path deliberately.

7. Keep the happy path short

Every field you add between "user opens link" and "booking exists" costs conversions. For a salon or a clinic, the useful minimum is:

Service
Time
Name + phone

Address, date of birth, insurance ID, gender, "how did you hear about us" — none of them belong in the first booking. Collect them later, or never. A phone number is also your recovery path when a no-show is about to happen.

Where this lands

None of this is exotic. It is the accumulation of small refusals: refusing the spinner, refusing the silent retry, assuming the network will fail and making that failure visible and recoverable.

Do that and the flow works on the phone your customer actually owns, not the one in your demo video.

If you want to see the whole thing assembled — QR entry, live queue, WhatsApp confirmations and reminders — SWIQ runs it as a product for Indian clinics, salons and service counters, and you can try a free demo with no card.

For the wider context, this piece on appointment booking software with WhatsApp covers the notification workflows in more depth, and this comparison of appointment booking apps in India covers the platform landscape.

Designing a Real-Time Token Queue: What We Learned Building Appointment Systems

Nitin Doyal — Sat, 10 Oct 2026 12:56:32 +0000

A token queue looks like a trivial problem until you build one. It is a sorted list with a counter — surely the simplest thing you can ship?

It is not. The failure modes are all in the edges: two people joining in the same second, a staff member serving out of order, a phone that reconnects after four minutes underground, and a customer staring at a number that has not moved in eleven minutes wondering if it is broken.

We have spent time working through how token-based queue and appointment systems behave in production for Indian clinics, salons and service counters. Here is what actually matters when you design one.

1. The queue is not a list — it is an event log

The tempting model is an array of tokens with a currentIndex. Do not do it.

If your source of truth is "the current position", you cannot answer the questions that matter:

How long did this customer actually wait?
Which counter is the bottleneck?
How many joined and never got served? (Your walk-away rate.)
What was the queue state at 4:12 pm last Tuesday?

Model every transition as an event instead: joined, called, served, skipped, left. The current position becomes a fold over the log. Analytics become a query over the log. Disputes become a lookup.

This is the same reason billing systems keep ledgers rather than balances. You will be asked "why was I skipped?" and you need a defensible answer.

type QueueEvent =
  | { type: 'joined';  tokenId: string; at: number; channel: 'qr' | 'counter' | 'api' }
  | { type: 'called';  tokenId: string; at: number; counterId: string }
  | { type: 'served';  tokenId: string; at: number; counterId: string }
  | { type: 'skipped'; tokenId: string; at: number; reason: string }
  | { type: 'left';    tokenId: string; at: number }

2. Ordering must be decided at join time, not read time

The classic race: two clients hit POST /queue/join concurrently, both read max(position), both write max + 1. One customer's place silently disappears.

Fix it at the database, not in application code:

A serialised counter row (SELECT ... FOR UPDATE), or
A monotonic sequence / SERIAL column with the position derived from it, or
An append-only table where position is assigned by the insert transaction.

Whatever you choose, the invariant is: position is assigned atomically with the join, and no read path ever computes it. Under load, the bug appears maybe one shift in fifty — which is exactly the frequency that destroys trust in the product.

3. Real-time delivery needs a fallback that is boring

Push updates (WebSocket or SSE) make the customer's screen feel alive. They also fail constantly on mobile networks.

Design for it from the start:

Snapshot first, then deltas. On connect, send the full state. Only then stream changes. A client that reconnects mid-queue must be able to rebuild without replaying history.
Sequence numbers on every message. Gap detected → refetch snapshot. Do not try to be clever about resuming.
Polling as a first-class path. A 15-second poll is an acceptable degraded mode. Many customers are on patchy 4G; the experience must not depend on a persistent socket.
Heartbeats with a short timeout. Detect dead sockets quickly so you stop counting phantom viewers.

Honest note: for most counter queues, a well-built 10-second poll outperforms a fragile WebSocket implementation. Ship the poll, add push when you have measured the need.

4. Serving out of order is a feature, not a bug

Reality at any counter: token 14 is a no-show, token 15 has to leave for a school pickup, and the receptionist serves token 17 because it is a five-minute form fill.

A rigid FIFO queue forces staff into workarounds — which means the software stops matching reality within a day.

Support explicit, auditable transitions instead:

skip (customer not responding) with a required reason
recall (bring them back)
priority (genuine cases: accessibility, emergencies at a clinic)
reorder with a permission check

Every one of these must be an event with a timestamp and an actor. If you cannot reconstruct why someone was served out of order, you will lose the argument at the counter.

5. Merge booked appointments with the walk-in queue

Booking systems and walk-in queues are usually built as two separate features. In practice they are one problem.

A customer who booked 3:00 pm and a customer who walked in at 2:55 pm are competing for the same chair. If you keep two lists, your double-book rate climbs until staff start managing on paper again.

The workable model:

Booked appointments occupy slots on a resource (a stylist, a room, a counter).
Walk-ins fill gaps between slots, estimated by real historical service duration.
Late arrivals degrade into the walk-in queue rather than silently breaking the slot.
One ordered view is presented to staff; customers only see their own position and estimate.

That last point matters: customers do not need global ordering, they need an honest estimate and a signal when they are close.

6. Waiting time beats position as the UX

"you are 7th" is a weak message. Seven at a quiet clinic is four minutes; seven on a Monday morning is forty.

Two improvements:

Show an estimate with a range — "about 20–30 minutes" — and refresh it as observed service times change. Ranges survive variance; precise numbers do not.
Notify on distance, not on position — "your turn is next" when they are 2 away, so they can come back from the car park.

Never promise a time you cannot hit. An estimate that runs long is worse than no estimate at all, because it converts a patient wait into a complaint.

7. Analytics is the real product

The token display is what the customer sees. The reporting is what the business owner pays for.

Worth having from day one:

Metric	Why it matters
Median wait by hour	Flat the peaks; staff to the real load
Service time p50 / p95 per staff	Separates slow service from slow systems
Joined vs served	Your walk-away rate — the money leak
Booking share vs walk-in	Whether the link is actually working
No-show rate	Whether reminders are earning their cost

p95 matters more than the mean. One 40-minute colour service will drag the average and hide the fact that everything else ran at 12 minutes.

8. Operational details nobody thinks about

Idempotency keys on join. Mobile connections retry. Duplicate tokens are embarrassing and common.
Timezone in storage and in display. Store UTC, render in the business's timezone, and show it. Indian businesses operate IST; daylight-saving bugs are rare here but off-by-one-day bugs are not.
Offline-tolerant staff UI. The receptionist's screen must keep working through a 30-second drop, then reconcile.
A kill switch per counter. Sometimes you just need to pause intake because the doctor stepped out.

The takeaway

The queue itself is easy. The hard parts are concurrency, honesty about time, and letting staff break the order without breaking the data.

Get those three right and the system survives contact with a busy Saturday — which is the only benchmark that counts.

If you want to see a production version of this in action, SWIQ runs a queue and booking system built for Indian clinics, salons and service counters — live token tracking, a QR booking page, and WhatsApp turn alerts, with a free demo at swiq.services/landing.

Further reading: this guide to appointment booking with live tokens covers the customer-facing flow, and this queue management system guide covers the operational side.