# Research notes This spec describes a scheduling app modelled on the design of Cal.com, the open-source scheduling product (AGPL-3.0). Everything here is described in our own words from watching the public product and reading how it behaves. No source code, text, images, icons or branding were copied, and the built app must not use any of them (see "Names and words" in `spec.md`). ## How it was studied With REA (Reverse Engineer Anything, `rea-agents` 6.9.0 from npm, the official package of github.com/morluto/rea), on 2026-11-15: - `rea inspect-web-page` against a live public booking page in headless Chromium over CDP, with accessibility text and storage key names. It gave the page's structure: three columns (event details, month grid, times), spoken names on every day button ("Monday, November 16, 2026", "..., Unavailable", "..., Out of office", "..., Today"), and the 12h/24h group. - `rea capture-browser-scenario` runs of the same page (one in UTC, one with the browser in `America/New_York`), stepping through next month, previous month, the 24h toggle and picking a time, with accessibility and screenshots after each step and the network recorded. It showed: - the state kept in the address: `?month=YYYY-MM&date=YYYY-MM-DD` and then `&slot=` once a time is picked; - the visitor's zone shown under the details with a "Timezone Select" combobox, and every time button named with its zone; - previous-month disabled on the current month; the selected day pressed; today marked; - the slot list fetched for the whole visible grid as one UTC range (for example 2026-11-30 to 2027-01-02 for December), by username, event slug and a reschedule uid when moving a booking; - the booking form fields (name, email, notes, add guests) and the Back and Confirm buttons, replacing the calendar in place; - the "requires confirmation" flag shown in the details column. - `rea import-reference-source` on the open-source repository (commit `ae027bb7`, 2026-11-13) to inventory the scheduling modules, which were then read to learn the rules: weekly hours plus date overrides read as wall clock in the schedule's zone (kept at the same wall time across DST), minimum notice (default two hours), buffers before and after, a slot step, per-day and how-far-ahead limits, booking statuses (accepted, pending, cancelled, rejected), reschedule creating a new booking and cancelling the old one with a link back, and the host's bookings tabs. Evidence files (kept by the spec author, not shipped): the inspect and scenario Evidence JSON, per-step accessibility text and screenshots. ## Where this spec chooses differently - **Slot alignment.** The original rounds slot starts to round minutes in the visitor's zone, so a visitor in a half-hour zone can see different starts from one in a whole-hour zone. This spec counts slots from the start of each available range in the host's zone, so every visitor sees the same instants (slot test 14). - **Pending bookings block their slot.** The original lets the host choose; here an unconfirmed request always holds its time, which avoids two people asking for the same slot. - **Smaller scope.** No teams, routing, workflows, payments, integrations or email; see "Out of scope" in `spec.md`. - **Runs on Cloudflare.** The original is a Node.js app on PostgreSQL. This spec targets one Cloudflare Worker with static assets and D1, with no Node.js built-ins. D1 has no interactive transactions, so the "check then insert" of a booking is done as one conditional `INSERT ... SELECT ... WHERE NOT EXISTS` (atomic in D1) instead of a locked transaction or a Durable Object, and bookings keep their buffers so the guard needs no join. Passwords use Web Crypto PBKDF2 (100000 iterations, the Workers maximum) instead of bcrypt. ## Checked by building it A build from these files ran under `wrangler dev` with a local D1 (no Cloudflare account): 14 slot unit tests and 12 Playwright tests passed, including both double-booking races and a same-start reschedule. With the `computeSlots` pre-check turned off, both races still gave one booking per time and never two overlapping ones, so the SQL guard holds by itself. A separate fresh build made only from `spekkr.json`, `spec.md`, `design.md` and `tasks.md` passed R1 to R13 (14 slot tests, 9 Playwright tests); the gaps it reported were then fixed in this version. `wrangler deploy --dry-run` bundled the Worker (about 63 KiB gzipped) without Node.js compatibility flags.