public
imalexnord
read
Slot
Calendar-first scheduling powered by Cloudflare Workers and Google Calendar.
Languages
Repository composition by tracked source files.
TypeScript
79%
CSS
19%
SQL
2%
HTML
0%
Create file
Wiki Documentation
Clone
https://nobgit.com/user/imalexnord/slot.git
ssh://[email protected]:2222/user/imalexnord/slot.git
Trace
ARCHITECTURE.md
Trace helps you understand code history line by line. See who changed each line, when it changed, and which commit introduced it.
Author
Date
Commit
Line
Code
1
# Architecture
3
```text
4
Visitor
5
│
6
▼
7
your-booking-domain.example
8
│
9
├── static React UI ───────────────┐
10
│ │ one Worker deployment
11
└── /api/* Cloudflare Worker ──────┘
12
│
13
├── D1
14
│ settings
15
│ bookings
16
│ OAuth token (AES-GCM encrypted)
17
│ OAuth state
18
│ short-lived slot locks
19
│ basic rate limits
20
│ Stripe payment/refund state
21
│ reschedule proposals (hashed bearer tokens)
22
│ append-only admin activity events
23
│
24
├── Google Calendar API
25
│ FreeBusy
26
│ Event creation
27
│ Google Meet creation
28
│ attendee invitation
29
│
30
└── Stripe API
31
Checkout Sessions
32
PaymentIntent refunds
33
signed payment/refund webhooks
34
```
36
## Booking transaction
38
1. Calculate candidate times inside weekly availability.
39
2. Subtract Google FreeBusy ranges and recent D1 reservations.
40
3. Visitor chooses a start and duration.
41
4. Server recomputes availability rather than trusting the browser.
42
5. D1 reserves each time segment touched by the booking and buffers.
43
6. Google FreeBusy is checked once more.
44
7. If payment is disabled, the normal Google event is created and the booking is confirmed immediately.
45
8. If payment is enabled, Slot creates a **private owner-only Google Calendar hold** with no attendee invitation. A Google Meet conference may be attached to the hold internally, but it is not exposed to the visitor.
46
9. Stripe Checkout opens for the calculated duration × per-minute rate. The Checkout Session expires after 30 minutes.
47
10. A signed Stripe webhook is the primary fulfillment signal. Only after `payment_status=paid` does Slot convert the private hold into the attendee event, send Google Calendar updates, expose the Meet link, and mark the booking confirmed.
48
11. Cancelled or expired Checkout sessions release the private hold and D1 locks. A return-page status check provides an idempotent fallback if the webhook and browser redirect arrive in the opposite order.
50
## Why D1 exists
52
Google Calendar owns calendar truth. D1 only holds application state Google does not provide: UI settings, booking metadata, encrypted OAuth credentials, concurrency locks, payment/refund state, and the admin activity history.
54
## Booking management
56
A direct admin reschedule acquires short-lived D1 locks for the destination, rechecks Google FreeBusy, PATCHes the existing Google Calendar event with `sendUpdates=all`, and then moves the D1 booking record. The booking ID and Stripe payment remain the same.
58
A suggested new time does **not** move or release the original booking. Slot stores the proposed start/end plus a SHA-256 hash of a random bearer token, then PATCHes the Google event description with a secure acceptance URL using `sendUpdates=all`. When the attendee accepts, Slot re-runs normal availability checks before moving the existing event.
60
For a paid cancellation, Slot creates an idempotent full refund using the stored Stripe PaymentIntent before finalizing cancellation. Refund webhook events keep the D1 refund status current. If the configured Stripe mode does not match the payment's Checkout Session mode, Slot refuses the paid cancellation rather than cancelling without a safe refund path.
62
Every booking also has a separate high-entropy public booking ID (`SLT-...`). It is shown to the attendee on confirmation and written into the Google Calendar event description. The public cancellation endpoint accepts only this reference, rate-limits attempts, requires a future confirmed booking, and then delegates to the same cancellation/refund function used by Admin. The internal UUID remains the relational key and is not used as the guest-facing cancellation reference.
65
## Activity history
67
Slot writes lifecycle events to `activity_events` after successful booking, payment, reschedule, suggestion, refund, cancellation, and payment-hold transitions. Idempotency keys suppress duplicate webhook events. Activity writes are deliberately non-blocking so analytics can never make a booking or refund fail. The Admin Activity endpoint computes aggregate booking metrics from the booking table and reads the latest activity events for the chronological feed. Monetary totals stay grouped by currency.
70
## Optional paid durations
72
Stripe is optional. When Stripe payments are enabled, `paymentFreeDurations` can mark selected configured meeting lengths as free. Booking creation decides whether Checkout is required from the selected duration. Free bookings take the normal immediate-confirmation path; paid bookings use the Stripe hold/Checkout/fulfillment path.
74
## Public booking management
76
Confirmed bookings expose a high-entropy public `SLT-...` reference. The public Manage booking flow uses that bearer reference to load limited booking metadata and lets the attendee cancel or reschedule an upcoming confirmed booking. Rescheduling preserves duration and existing payment state, rechecks live availability, and updates the existing Google Calendar event. Public management endpoints are rate-limited.