DOCSEARCHbyAlgolia
Submit Docs

Compass Calendar Documentation

website·Indexed 32 days ago

https://docs.compasscalendar.com

Technical documentation for Compass Calendar, covering self-hosting architecture, server setup, and backup/restore procedures. Includes developer guides for local development, CLI commands, and testing with Bun 1.3.14, as well as product specifications for calendar providers (Google, Apple, Microsoft), booking interfaces, and keyboard shortcut parity.

Tokens
81.7K
Snippets
230
Records
573
Agent score
54%

What's inside Compass Calendar

  1. Overview of the Agent Loop Routine

    The agent-loop is an autonomous routine that manages the lifecycle of GitHub issues across ordered milestones. It automates the flow from issue identification to PR creation, merging, and staging smoke tests. It uses milestone-specific prompts located at .github/prompts/<milestone-slug>.md (falling back to .github/prompts/agent-loop.md) and execution scripts located in .github/scripts/agent-loop-*.sh.

  2. Overview of Compass Calendar Provider Support

    Compass supports three major calendar hosts: Google Calendar, Microsoft (Outlook/Office 365), and Apple (iCloud). The system ensures consistent behavior across providers for event imports, bidirectional edits, recurring series, and booking availability.

    Key provider characteristics:

    • Google: Full OAuth integration with push notifications and Google Meet support.
    • Microsoft: Uses the /common endpoint to support both personal and work/school accounts. Supports Microsoft Teams conference links.
    • Apple (iCloud): Implemented via CalDAV using app-specific passwords. Does not support push notifications; freshness is maintained via polling every 60 to 90 seconds.

  3. Overview of the Cursor Cloud VM environment

    The Cursor Cloud VM uses Bun (bun@1.3.14) as the runtime and package manager. The environment is initialized via .cursor/environment.json, which installs Bun and runs bun install on boot. General development rules are located in AGENTS.md.

  4. Overview of Google Calendar integration modes

    Compass Calendar offers three modes for Google integration, affecting how users sign in and how calendar data synchronizes. The sync container handles the calendar-sync lifecycle (importing, watching, and pushing edits), while the main backend handles Google OAuth sign-in.
    ModeWhat it doesWhat you needWho it's for
    Off (default)Google sign-in and connect actions are hidden. Email/password signup works normally.Nothing.Users not needing Google.
    Local developmentGoogle sign-in and initial import work. Changes in Google Calendar are polled every ~10 mins (no push notifications).Google Cloud OAuth client (localhost) + compass.yaml config.Bun-based local setups.
    Public, fully-live syncFull two-way sync with near-instant updates via Google push notifications.Public HTTPS URL (sync.callbackBaseUrl) + real Google OAuth credentials.Server installs.

  5. Overview of the Error Autofix Routine

    The error-autofix routine is an unattended workflow designed to govern the lifecycle of production error fixes. It is triggered by PostHog bots opening/reopening issues, an hourly sweep, or manual workflow_dispatch. The routine uses a specific prompt (.github/prompts/error-autofix.md) to generate issue comments or Pull Requests that reference the original issue. It includes a preflight check to prevent duplicate work and a merge-guard script to verify PR size before merging.

  6. Overview of Compass CI/CD Workflows

    Compass utilizes GitHub Actions for CI, Docker Hub for image distribution, and a VPS for staging. The pipeline consists of several specialized workflows:

    • Testing & Quality: Unit (lint, type-check, unit tests), E2E (Playwright shards), CodeQL (security analysis), and Performance budget (Lighthouse).
    • Automated Routines: Error autofix (PostHog issue triage) and Agent loop (milestone-based development and merge queue).
    • Deployment: Release on main (auto-patch, publish, and staging deploy), Publish Docker images, Deploy staging, and Deploy production.
    • Maintenance: Deploy health check and Sync docs (mirrors docs to the public site).
    • Smoke Testing: Live provider smoke (nightly adapter contract tests).

  7. Understand the Compass backend request flow and architecture

    The Compass backend follows a consistent route -> controller -> service pattern with a middleware-heavy setup. The responsibilities are split as follows:

    • Route Config: Defines the Express path and middleware composition.
    • Controller: Handles request parsing and response orchestration.
    • Service: Contains the core business logic.
    • Query/Repo Layer: Manages database-specific access.

  8. Implement Architectural Patterns in Compass

    Follow these established patterns when adding new functionality:

    • Backend Routes: Follow the flow: routes.config.ts -> controller -> service -> query/mongo.
    • Web State Management: Use a mixed architecture:
      • Zustand: Transient client state (drafts, view dates, cmd palette).
      • TanStack Query: Persisted event reads/mutations and deduplication.
      • IndexedDB: Offline event storage.
    • Shared Schemas: Define the schema with Zod, export the inferred TypeScript type, and consume that contract in both the web and backend packages.

  9. Coordinate Frontend State Systems

    The application uses a layered state architecture. Developers must not mirror persisted Event entities into Zustand stores or call IndexedDB directly from components.

    ConcernTechnologyKey Path
    Event loading, fetching, read errorsTanStack Query range cachesapps/calendar-web/src/events/queries/
    Event mutations (create/edit/delete)TanStack Query mutationsapps/calendar-web/src/events/mutations/
    Draft Events & interaction stateZustand draft storeapps/calendar-web/src/events/stores/draft.store.ts
    View dates, cmd palette, user metadataZustand stores.../events/stores/view.store.ts, .../settings/settings.store.ts
    Offline persistenceIndexedDBapps/calendar-web/src/common/storage/offline-data/indexeddb-offline-data.store.ts
    Local vs remote persistence logicRepository factoryapps/calendar-web/src/events/repositories/event.repository.util.ts

    Zustand Pattern: Stores are created with create()(devtools(...)) and paired with module-level action functions. Selectors must return primitives or stable references (use useShallow for new objects).

  10. Access Meeting Monitoring Dashboards in PostHog

    Meeting monitoring is managed in PostHog project 165441 (Switchback, UTC). The source of truth for insight windows, populations, and alert evaluation is located at packages/scripts/src/telemetry/meeting-dashboard.ts.
    # Source of truth for telemetry logic:
packages/scripts/src/telemetry/meeting-dashboard.ts

  11. Understand the Compass event caching model

    Compass uses TanStack Query as the primary cache and single owner of persisted events. Events are stored in a normalized { ids, entities } shape, where each cache entry represents a specific 'window' defined by a source, scope, and date range. Zustand stores are used only for transient drafts and interaction state, not for persisted events.

  12. Google Calendar Sync UX Principles

    The Google Calendar sync, authentication, and session UX is designed to minimize user distraction and prioritize data integrity. The core principles are:

    • Prefer Silent Background Recovery: Token refreshes, watch repairs, and incremental catch-ups should happen automatically without notifying the user or triggering error toasts.
    • Clear Progress Indicators: When a process is running and no user action is needed (e.g., "Adding your calendar..."), the UI should calmly inform the user that data will catch up soon.
    • Unmistakable Action-Required States: When recovery is impossible (e.g., revoked OAuth access), the UI must immediately signal the need for reconnection across all relevant surfaces before the user attempts to perform work that cannot be saved.
    • UI Consistency (One Story): Toasts, sidebar status, and Settings/Accounts status must always be congruent. If a reconnect is required, no surface may claim the connection is healthy.
    • Durable Truth: Terminal failures must not be overridden by transient "healthy" or "importing" signals to avoid "optimistic flicker" where a user thinks a problem is solved only to have a subsequent write fail.