Topolo Calendar

What It Is

Topolo Calendar is the scheduling application for public booking pages, availability management, invitations, and booking lifecycle controls 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, writes slot holds through to D1, 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, booking confirmation, and token-backed invitee manage links under /api/public/*. The authenticated host-management API lives under /api/admin/* for host profile, event type, availability rules and overrides, booking detail/edit/reschedule/cancel/resend actions, and external-calendar free/busy sync scaffolding.

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, attendees, delivery receipts, persisted slot holds, recurrence series, public manage-token hashes, external-calendar metadata, and imported external busy blocks. 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 until native provider adapters are connected.

Invitations and Manage Links

Calendar emits calendar.booking.invite_requested, calendar.booking.updated, calendar.booking.cancelled, and calendar.booking.reminder_due events through TopoloNotify after booking persistence succeeds. The notification payload includes a Calendar-built RFC5545 .ics attachment with stable UID, incrementing SEQUENCE, METHOD:REQUEST for create/update/reminder, and METHOD:CANCEL for cancellation. Invitees receive token-backed manage links at /manage/<token> for view, cancel, and reschedule without a Topolo account.

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.

Recurrence and Sync Scope

Calendar supports a bounded RFC5545 recurrence subset for daily, weekly, and monthly series with interval plus count or until limits. The Worker materializes occurrences for the next 18 months and records edited or cancelled occurrence exceptions. External calendar sync is provider-neutral at the core: Google Calendar, Microsoft Graph, and CalDAV adapters import free/busy blocks into external_busy_blocks, and the same conflict engine checks confirmed bookings, persisted holds, availability overrides, and external busy blocks.

Failure Modes

• Google/Microsoft OAuth sync requires active Calendar app credentials in Nexus; CalDAV sync requires Calendar’s connection encryption key before hosts can connect provider calendars
• invitee manage links are bearer tokens; stale or rotated links return invalid_or_stale_token
• TOPOLO_NOTIFY_URL or TOPOLO_SERVICE_CLIENT_SECRET missing prevents invite/update/cancel/reminder delivery while leaving booking persistence intact

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.
• Moved Google/Microsoft Calendar OAuth app client credentials out of Calendar Worker secrets and into Nexus generic integration app credentials on 2026-06-01.
• Added calendar invite/update/cancel/reminder Notify events, Calendar-owned ICS generation, public manage links, admin booking lifecycle actions, availability overrides, recurrence materialization, persisted holds, and native Google/Microsoft/CalDAV free/busy sync on 2026-06-01.
• 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.