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 under service id srv_topolo_calendar. 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 a Chat meeting once that bridge is enabled. External providers (Microsoft Teams, Google Meet, Zoom) are brokered through Topolo Nexus for metering.

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.

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 srv_topolo_calendar.

Change Log / Verification

• 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 srv_topolo_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.