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.

Workspace Management

The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces.

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 app 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-io/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 sync projections, stable Nexus connection references, and imported external busy blocks. Nexus is the sole owner of Google, Microsoft, and CalDAV provider identity, lifecycle state, errors, scopes, expiry, and credentials under app_topolo_calendar; Calendar resolves the connection only while connecting or syncing and does not persist provider credentials in D1. 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.

Mobile Experience

The checked-in mobile experience contract is approved in native_capability mode. Its fallback route is /agenda, its offline policy is read_through_cache, and it requires organization context.

Published permissions: bookings:read, bookings:write.

• /agenda uses /api/admin/bookings with the calendar.agenda template and calendar.agenda.list data source.
• /agenda/:id uses /api/admin/bookings/:id with the record.detail template and calendar.agenda.detail data source.

The native clients consume this manifest as an explicit rendering contract. A web mode record intentionally opens the product web experience; native_capability publishes the listed native routes and actions. Do not infer unlisted native behavior.

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 and CalDAV sync require an active Nexus connection under app_topolo_calendar; missing, disconnected, deauthorized, deleted, or error-state connections fail closed
• rows migrated from Calendar's retired local credential store have no canonical Nexus reference and remain disconnected until the host reconnects the provider
• 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 app id resolved from topolo-calendar.

Use It

Open Calendar for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-calendar --json
topolo actions --service topolo-calendar --json
topolo actions capabilities --service topolo-calendar --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

1. Confirm the active identity and organization with topolo whoami --json.
2. Discover Calendar and select one published action rather than guessing a route.
3. Inspect its input/output schemas and published example.
4. Validate and plan the exact payload; obtain confirmation for a mutation.
5. Execute and perform every published verification step.

Change Log / Verification

• Completed the approved Calendar staging protection proof at exact source 4e5380c0ddaf5909184891cbbff9d07b189ea33c, API version fe115b97-773d-49e4-bef3-1c1d79a74afb, and web version d3f38b3c-48b1-411b-8427-1f5e4d43bcc1 on 2026-08-03. Restricted scheduling data uses versioned application-layer encryption and purpose-bound keyed hashes. Dry-run, real, and repeat migration passes reported zero remaining plaintext; the baseline canary reported 54 protected fields with zero failures/plaintext. A synthetic host, external calendar, and busy block round-tripped through the published action surface while the canary remained clean; cleanup returned the final canary to 54 protected fields with zero failures/plaintext. Production promotion remains separately authorized.

• Removed the stale action-coverage exclusion for Calendar's retired credential-convergence route at staging commit 2ab76973224b on 2026-08-01. The exact source audit now classifies all 48 served routes with zero gaps, dead actions, or invalid exclusions; staging API version 93de2cb8-d952-4ab2-9434-b85542f615d5 and web version 5196315c-ca71-47e7-b96b-83094ed6f29b passed the governed deployment.

• Reconciled canonical Nexus connection ownership against apps/TopoloCalendar staging commits 7d76370d7cf3, 4b2c7d6a3cef, and c49a36029ad2 on 2026-08-01. Calendar now retains only scheduling/sync projection state and a stable Nexus connection reference; Nexus owns provider identity, lifecycle, errors, scopes, expiry, and credentials, and the retired Calendar credential-store binding and re-encryption path are absent from the canonical manifest and runtime configuration.

• Retired Calendar's 2026-07-28 app-local credential protection and convergence path when canonical Nexus connection ownership landed on 2026-08-01; no compatibility route or credential-store binding remains.

• Verified the native_capability mobile experience contract and its 2 published route(s) against apps/TopoloCalendar origin/staging aca56ed07338 on 2026-07-27.

• Reconciled this page against apps/TopoloCalendar origin/staging 8f12c0d80378 on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract.

• Reconciled workspace verification on 2026-06-28 against apps/TopoloCalendar commits through 15b439e; reviewed 278 commits since 2026-06-01, including 15b439e chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); a2444d0 Adopt canonical Topolo typography; df2793d Split Calendar shell startup bundle; 22fa5bc Lazy load Calendar routes.

• Resolved Calendar app 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 app_* 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-io/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.