Collaborative Scheduling System

[bryanchriswhite]

Overview

Transform the current "instant schedule" flow into a collaborative scheduling system where participants view overlapping availability, vote on suggested times, and receive notifications about changes.

Background

Currently, when a topic reaches Stage 2 (minimum participants met), the owner can immediately schedule a session by clicking "Schedule Session" which hardcodes a time 1 week from now at 2 PM. This doesn't consider participant availability or allow for collaborative time selection.

Goals

• Allow participants to share their availability (via Google Calendar sync or manual entry)
• Generate deterministic time slot suggestions based on overlapping availability
• Enable participants to vote on preferred time slots
• Auto-confirm scheduling when consensus threshold is met (or owner decides)
• Notify participants of scheduling changes and conflicts
• Create Google Calendar events for confirmed sessions

Key Design Decisions

• Authority: Hybrid - auto-confirm when consensus threshold met, otherwise owner decides
• Calendar fallback: Manual availability entry for users without Google Calendar connected
• Notifications: Both in-app and email
• Time range: Configurable per topic (owner sets scheduling window when creating topic)

Implementation Phases

Phase 1: Data Model Extensions

• Extend Topic type with scheduling configuration
• Add TimeSlot, SchedulingPreference, AvailabilityWindow types
• Add Notification type
• Define GunDB storage structure for scheduling data

Phase 2: Availability Collection

• Create server/routes/scheduling.js with availability endpoints
• Create useAvailability hook for frontend
• Build AvailabilityInput component (manual entry + Google Calendar sync)

Phase 3: Time Slot Suggestion Algorithm

• Create server/services/slotGenerator.js
• Implement deterministic slot generation (same input = same output)
• Score slots by participant availability percentage
• Implement lock threshold logic (stop regenerating after N selections)

Phase 4: Scheduling UI

• Create SchedulingPanel component
• Add participant availability grid visualization
• Implement voting/selection flow
• Show progress toward consensus threshold
• Add owner "Confirm Selection" button for manual override

Phase 5: Notification System

• Create notification service (backend)
• Create notification API endpoints
• Build useNotifications hook
• Add NotificationBell component to header
• Implement email notifications (nodemailer)
• Set up notification triggers (slot invalidated, consensus reached, scheduled, etc.)

Phase 6: Calendar Event Creation

• Finalize scheduling flow with Google Calendar event creation
• Handle participants without Google Calendar (email-only invite)
• Error handling for failed calendar operations

New Files to Create

• client/src/components/SchedulingPanel.tsx
• client/src/components/AvailabilityInput.tsx
• client/src/components/NotificationBell.tsx
• client/src/hooks/useAvailability.ts
• client/src/hooks/useScheduling.ts
• client/src/hooks/useNotifications.ts
• server/routes/scheduling.js
• server/routes/notifications.js
• server/services/slotGenerator.js
• server/services/notifications.js

Files to Modify

• client/src/types/index.ts - Extended types
• client/src/components/TopicCard.tsx - Scheduling progress display
• client/src/components/Dashboard.tsx - Wire up SchedulingPanel
• client/src/components/Header.tsx - Add notification bell
• client/src/components/CreateTopicModal.tsx - Add scheduling config options
• server/index.js - Mount new routes

Open Questions / Future Considerations

• Timezone handling for participants in different zones
• Recurring event scheduling complexity
• Calendar polling frequency for conflict detection
• Rate limiting for notification emails

Acceptance Criteria

• Participants can submit availability (manual or Google Calendar)
• System generates deterministic time slot suggestions
• Participants can vote on preferred slots
• Topic auto-schedules when consensus threshold met
• Owner can manually confirm if no consensus
• Participants receive in-app and email notifications
• Google Calendar events created for confirmed sessions
• Participants notified when their selected slot becomes invalid