⛰️ EPIC - Add support for Google sub-calendars

[tyler-dane]

Feature Description

Sub-Calendars Integration: Schema CRUD, and UI Controls

Overview

Enable Compass users to import, view, and manage events from Google sub-calendars in addition to their primary calendar. This includes CRUD operations for events in each calendar, toggling calendar visibility in the UI, color-coded event identification, and real-time notifications per calendar.

Goals

• Allow users to import all Google calendars (primary and sub-calendars).
• Enable CRUD operations for events in any imported calendar.
• Provide UI controls to toggle visibility of individual calendars.
• Display events with calendar-specific colors for easy identification.
• Support websocket notifications scoped to calendar changes.
• Ensure seamless user experience for multi-calendar management.

Requirements

• Backend: Extend calendar sync logic to import all user calendars, not just primary.
• Backend: Store standardized calendar metadata (id, name, color, etc.) for each imported calendar.
• Backend: Define new Compass Calendar Zod Schema
  • Metadata field will be provider specific - containing provider specific calendar details
  • Create an any of validation schema per provider metadata - "$jsonSchema" use zod-to-json-schema
• Backend: Map Calendar data to Compass Calendar data
• Backend: CRUD endpoints for events must accept calendarId and operate on the correct calendar.
• Backend: Websocket notifications must be scoped to calendarId.
• Frontend: Sidebar UI for listing all imported calendars with toggles.
• Frontend: Events rendered with calendar color.
• Frontend: Events rendered in grid view per calendar overlay
• Frontend: CRUD event forms allow selection of target calendar.
• Frontend: Persist calendar visibility preferences per user.
• Core: Update types and mappers to support multiple calendars.
• Testing: Unit/integration tests for multi-calendar CRUD and UI toggling.

Scope/Constraints

• Only Google Calendar integration is supported for sub-calendars.
• Calendar sharing, permissions, and non-Google providers are out of scope.
• Mobile app support is not included.
• Performance must be maintained for users with many calendars/events.
• UI must remain intuitive and not cluttered.

Acceptance criteria

• Users can import all their Google calendars (primary + sub-calendars).
• Users can view a list of calendars in the Compass sidebar and toggle visibility.
• Events from visible calendars are shown in the UI, color-coded by calendar.
• Users can create, edit, and delete events in any imported calendar.
• Websocket notifications are received only for visible calendars.
• Calendar CRUD operations work for all imported calendars.
• Calendar visibility preferences persist across sessions.
• Schema and user journey diagrams are updated and documented.

Business use case

Busy professionals and teams often manage multiple calendars (work, personal, project-specific). Supporting sub-calendars in Compass enables users to organize, view, and act on events across all their calendars in one place, improving productivity and reducing context switching.

User Journey

flowchart TD
    A[User logs in] --> B[Compass imports all Google calendars]
    B --> C[Sidebar displays calendar list with toggles]
    C --> D[User toggles calendar visibility]
    D --> E[Compass UI updates to show/hide events by calendar]
    E --> F[User creates/edits/deletes event, selects calendar]
    F --> G[Compass syncs event to correct Google calendar]
    G --> H[Websocket notifications sent for calendar changes]

Loading

Warning

This is a large, advanced backend feature that is broken down into sub-issues

Follow-up Issues
• #TODO: Keep subcalendars and events in sync after the initial import
• #TODO: Update onboarding and account settings flow to reflect calendar selection and visibility
• #TODO: Add feature flag support for premium calendar sync