Topolo Calendar

What It Is

Topolo Calendar is the scheduling application for public booking pages, availability management, and cross-app event feeds across the Topolo platform. Hosts publish event types at calendar.topolo.app/<handle>/<event-type> and invitees book timeslots without needing an account.

Architecture

Calendar is a Cloudflare-native Worker with D1 as the system of record and a per-host Durable Object (CalendarHostDO) acting as the hot-path coordinator. The DO serialises booking attempts, owns short-lived in-memory slot reservations, caches availability windows, and writes confirmed bookings to D1 before acknowledging success.

Runtime Surfaces

The primary public surface is https://calendar.topolo.app. The root page renders Topolo’s shared landing page from Auth-managed Calendar landing config. Public booking pages live at /<handle>/<event-type>. The authenticated admin UI is served from /app inside Topolo’s shared application shell, with the app switcher preloaded during shell boot and a weekly Calendar workspace as the default signed-in view.

API Reference

The public booking API exposes host lookup, event-type lookup, availability probing, booking holds, and booking confirmation under /api/public/*. The authenticated host-management API lives under /api/admin/* for host profile, event type, availability rule, booking list, and booking cancellation actions.

Auth and Permissions

Calendar uses Topolo Auth for workspace access through the stable service slug topolo-calendar; the Worker and browser resolve the current environment’s concrete Auth service id before login, callback exchange, widget responses, and admin Auth middleware checks. Public booking endpoints are unauthenticated so invitees can load a page, probe availability, place a temporary hold, and submit a booking. Admin endpoints (/api/admin/*) require a valid bearer token through the shared Auth middleware and enforce the matching Calendar service-scoped permissions for host, event type, availability, and booking actions.

Calendar’s admin sign-in uses the shared first-party Topolo login page on calendar.topolo.app/login, with embedded email/password sign-in, password reveal, signup handoff, Auth-backed password submission, and /auth/callback completion. After first sign-in, users without a Calendar host profile complete the shared @topolo/onboarding first-run flow to choose their booking handle, display name, and timezone before the admin dashboard opens. Public invitee booking flows remain account-free.

Data Ownership

Calendar owns hosts, event types, availability rules and overrides, bookings, in-memory slot holds, and external-calendar sync metadata. The D1 schema reserves a slot_holds table for future persisted hold audit rows, but the current Worker keeps holds in the per-host DO until confirmation or expiry. Meeting sessions (join tokens, transcripts, realtime state) remain owned by Topolo Chat; Calendar stores a meetingProviderRef pointing at the created Chat meeting for Topolo Chat event types. External providers (Microsoft Teams, Google Meet, Zoom) remain configurable per event type by storing the host-supplied meeting link or instructions on the booking.

Deployments

Calendar deploys as the Cloudflare Worker topolo-calendar with static assets bound through ASSETS, a D1 binding named DB, and the CALENDAR_HOST Durable Object binding. The production domain is calendar.topolo.app; staging mirrors it at calendar.stg.topolo.us with a staging-specific browser build so Auth and app-origin calls stay inside the staging installation.

Embedding on External Sites

Calendar ships an embed SDK (@topolo/calendar-embed) with three modes — inline iframe, popup trigger, and floating bubble — plus a @topolo/calendar-react wrapper. Embed origins are verified against the service manifest’s allowlist so the platform can attribute embed traffic back to a Topolo organization.

Cross-App Event Feed

CRM follow-ups, Commerce service bookings, Support appointments, and Learn cohort sessions publish events into Calendar through an internal API. This gives the platform a single time surface without every app rebuilding one.

Failure Modes

• external calendar sync drifts and introduces double-booking risk
• slot holds are currently in-memory, so DO eviction can expire an in-progress hold before invitee confirmation
• embed parent-origin verification lags service-manifest updates

Debugging

Start with /systems/topolo-calendar, then verify the DB and CALENDAR_HOST bindings. Public 4xx responses usually mean a missing host, missing event type, malformed JSON payload, unavailable slot, or expired hold. Admin 401 responses should be traced through Topolo Auth validation for the service id resolved from topolo-calendar.

Change Log / Verification

• Resolved Calendar service identity from the Auth-owned topolo-calendar service slug on 2026-05-13 so the browser login/callback path, Worker widget payload, and admin Auth middleware no longer carry checked-in concrete srv_* ids.
• Verified Calendar staging origin isolation on 2026-04-30.
• Added configurable meeting providers on 2026-04-26: Topolo Chat event types now create Chat guest meeting links at booking confirmation, while Teams, Google Meet, and Zoom event types can carry host-supplied links or instructions.
• Replaced the signed Calendar admin page with the shared Topolo shell and default weekly Calendar workspace on 2026-04-22, including the preloaded app switcher and authenticated bookings list route.
• Replaced Calendar’s local first-run host setup form with the shared @topolo/onboarding shell and flow on 2026-04-22.
• Fixed Calendar admin permission checks on 2026-04-22 so Auth’s service-scoped Calendar grants unlock the admin API after sign-in.
• Replaced Calendar’s local root marketing screen with the shared landing page and registered Calendar as a first-party UI Kit app on 2026-04-22 so the deployed /login route exposes embedded email/password sign-in instead of the external-app provider-only prompt.
• Moved Calendar admin sign-in onto the shared app-origin first-party login surface on 2026-04-21 and seeded Auth plus Developers D1 so Calendar is a Topolo-owned platform app under the Topolo organization.
• Added canonical Calendar system coverage and aligned the public handbook with the current Worker, D1, Durable Object, and Auth contract on 2026-04-21.
• Enforced Calendar admin route permissions and provisioned the production D1 binding on 2026-04-21.