Calendar
Cloudflare-native scheduling and bookings application with public booking pages, embeddable widgets, and a cross-app event feed.
Documentation Map
What It Is
Cloudflare-native scheduling and bookings application with public booking pages, embeddable widgets, and a cross-app event feed.
Architecture
Owners: platform-experience
Source repos:
Dependencies: topolo-auth, topolo-chat, topolo-nexus, topolo-notify, applications-packages
Repo shape
No repo surface entries were detected from the registered repo paths.
Runtime Surfaces
Hosts:
https://calendar.topolo.app https://calendar.stg.topolo.us No wrangler surface was discovered under the registered repo paths.
API Reference
Coverage: curated
Source: PlatformApplications/TopoloDocs/src/content/public/applications/calendar.mdx
Source exists in repo: no
Calendar is a Worker + D1 + per-host Durable Object application. Runtime service identity resolves from the Auth-owned service slug topolo-calendar instead of checked-in concrete srv_* ids. D1 is the system of record for hosts, event types, availability rules, bookings, reserved slot-hold audit rows, and external calendar sync metadata. CalendarHostDO (keyed by host handle) serialises concurrent booking attempts, owns short-lived in-memory slot holds, and caches availability windows. Confirmed bookings are written through to D1 before the DO acknowledges success; when TOPOLO_NOTIFY_URL and TOPOLO_NOTIFY_API_KEY are configured, Calendar emits generic `application.notification.created` through @topolo/notifications after persistence so the host can be notified without rolling back bookings on notification failure. Meeting sessions remain owned by Topolo Chat; `chat_meeting` bookings call Chat's internal Calendar bridge and store the returned guest URL in `meetingProviderRef`, while external providers (Microsoft Teams, Google Meet, Zoom) store host-configured links or instructions until native Nexus provisioning is added. The public root renders the shared Topolo LandingPage from Auth-managed Calendar landing config. Public booking pages (/<handle>/<event-type>) and availability/hold/confirm endpoints are unauthenticated. The admin `/login` route renders the shared first-party Topolo login on the app origin, with embedded email/password sign-in enabled by the UI Kit first-party registry, login config reads through `/api/auth/*`, and one-time `sso_code` completion on `/auth/callback`. Initial `/app` boot retries one Auth cookie refresh after a 401 admin context response and redirects to `/login` after clearing local session state if refresh fails. Signed users without a Calendar host row complete the shared @topolo/onboarding first-run host setup flow before the admin workspace opens. Signed users with a host row enter the shared `TopoloAppShell`; Calendar supplies section metadata and workspace content while the UI Kit owns sidebar, header, account menu, mobile navigation, app-switcher mount, launcher shortcut behavior, dark/light toggle, sidebar collapse, command palette, and BugFix reporter controls. Calendar scopes raw workspace CSS to app-owned containers so shared portal overlays keep package-owned styling. The default weekly Calendar view is backed by `GET /api/admin/bookings`. Calendar exposes `GET /api/widget` with the shared `@topolo/sdk` widget response contract for TopoloOne live workspace. Admin endpoints require bearer tokens validated by @topolo/auth-middleware against the resolved Calendar service id and enforce route-level Calendar service permissions, accepting Auth's service-scoped canonical grant form such as `<resolved-service-id>.host:read`. The embed SDK (@topolo/calendar-embed) supports iframe, popup, and floating bubble modes with a @topolo/calendar-react wrapper; embed origins are validated against the service manifest allowlist.
App API page: /reference/apps/topolo-calendar
This system currently relies on a curated or README-derived contract surface instead of a source-controlled OpenAPI spec.
Auth and Permissions
Depends on Topolo Auth: yes
Service IDs:
srv_4lfDYNsgOYTb API key scopes
Manage Calendar machine credentials
Resource pattern: none
Read weekly availability rules and overrides
Resource pattern: none
Update weekly availability rules and overrides
Resource pattern: none
List and inspect bookings
Resource pattern: none
Cancel or reschedule bookings
Resource pattern: none
Issue embed tokens for third-party websites
Resource pattern: none
List event types
Resource pattern: none
Create, update, or deactivate event types
Resource pattern: none
Connect or revoke external calendar sync sources
Resource pattern: none
View host profile and handle
Resource pattern: none
Create or update host profile, handle, and timezone
Resource pattern: none
Service permissions
api_keys:write, availability:read, availability:write, bookings:read, bookings:write, embed:issue, event_types:read, event_types:write, external_sync:write, host:read, host:write
Data Ownership
No storage bindings were derived from wrangler configuration.
Queues / Cron / Workflows
Queue bindings:
No queue bindings were detected.
Cron triggers
No cron triggers were detected.
Workflow signals
No explicit queue/workflow script or cron signal was discovered.
Environment Variables and Bindings
Environment variables:
No environment variables were derived from wrangler configuration.
All wrangler bindings
No bindings were derived from wrangler configuration.
Deployments
Deployment environments: default only or not declared
Routes: workers.dev or Pages-only delivery
Observability enabled: no explicit setting found
Failure Modes
- No wrangler.toml surface was discovered under the registered repo paths.
- The registered contract source is missing: PlatformApplications/TopoloDocs/src/content/public/applications/calendar.mdx
- Neither OpenAPI nor README-derived interface detail was found.
Debugging Runbooks
Start with these entrypoints:
- PlatformApplications/TopoloDocs/src/content/public/applications/calendar.mdx
Change Log / Verification
Lifecycle: active
Last verified: 2026-05-14
Any code change to this system is expected to update the canonical docs in PlatformApplications/TopoloDocs and refresh the verification date.