Calendar & Scheduling

Relevant source files

The following files were used as context for generating this wiki page:

• ai_backend/services/calendar_service.py
• ai_backend/database/calendar_models.py
• COMPETITIVE_ANALYSIS.md
• GAPS_IMPLEMENTATION_SUMMARY.md
• MISSING_INFO.md

The Calendar & Scheduling system in ClassMate provides integration with external calendar providers (specifically Google Calendar) to synchronize meeting data, manage reminders, and correlate recording sessions with scheduled events. Its primary purpose is to automate the metadata enrichment of lecture and meeting recordings by mapping them to existing calendar entries.

This module acts as a bridge between the AI Backend and third-party productivity suites. It allows the system to detect when a user is in a scheduled meeting and suggest relevant recording actions or automatically tag recordings with event summaries and attendee lists. Sources: ai_backend/services/calendar_service.py, COMPETITIVE_ANALYSIS.md:55-71

Architecture and Components

The scheduling architecture is built around a service-oriented pattern where the CalendarService manages external API communication and a set of SQLAlchemy models handle persistence.

Data Models

The system utilizes three primary database entities to manage scheduling information:

• User: Stores OAuth tokens and encryption keys for secure provider access.
• CalendarEvent: Represents a synchronized event from an external provider.
• MeetingReminder: Manages notification triggers for upcoming events.

Sources: ai_backend/database/calendar_models.py:10-72

Entity Relationship Diagram

The following diagram illustrates the relationships between users, their synchronized events, and associated reminders.

Google Calendar Integration

The system currently supports Google Calendar via OAuth 2.0. The CalendarService handles the flow from generating authorization URLs to exchanging codes for refresh tokens. Sources: ai_backend/services/calendar_service.py:18-30

OAuth and Synchronization Flow

The synchronization process involves fetching events for a defined window (defaulting to 7 days ahead) and persisting them locally for quick lookup.

Key Synchronization Methods

Method	Description	Parameters
get_google_auth_url	Generates the OAuth consent screen URL.	state (Optional)
handle_google_callback	Exchanges auth code for permanent tokens.	code
sync_google_calendar	Fetches and stores events from the 'primary' calendar.	user_id, days_ahead

Sources: ai_backend/services/calendar_service.py:53-133

Intelligent Meeting Detection

A core feature of the scheduling module is the ability to correlate a live recording session with a calendar event. The detect_meeting_from_session function uses a scoring algorithm based on time proximity and title similarity.

Matching Logic

1. Time Window: Looks for events within +/- 1 hour of the session start.
2. Proximity Score: Grants 50 points for matches within 5 minutes, and 25 points for matches within 30 minutes.
3. Content Score: Grants 10 points for every common keyword between the session title and event summary.
4. Threshold: A minimum score of 30 is required for a valid match.

Sources: ai_backend/services/calendar_service.py:228-275

# Matching threshold logic from source
if best_match and best_score > 30:  # Minimum threshold
    return {
        "id": best_match.id,
        "summary": best_match.summary,
        "match_score": best_score
    }

Sources: ai_backend/services/calendar_service.py:266-271

Security and Storage Considerations

Data privacy for calendar information is managed through specific security protocols, though some areas are identified as requiring future hardening:

• Token Storage: OAuth tokens are currently stored in the users table. The project roadmap specifies that these should be moved from plaintext to encrypted storage using EncryptionService. Sources: MISSING_INFO.md:7-13, ai_backend/database/calendar_models.py:56-62
• Scoped Access: The system requests calendar.readonly scopes to adhere to the principle of least privilege. Sources: ai_backend/services/calendar_service.py:59
• Encryption Keys: Users have associated encryption_key and public_key fields in the database to support end-to-end encryption of session data derived from these scheduled meetings. Sources: ai_backend/database/calendar_models.py:65-66

Summary of Known Gaps

Based on technical audits, the following limitations exist in the current implementation:

• Provider Support: Microsoft Graph/Outlook integration is currently disabled/removed from the CalendarService. Sources: ai_backend/services/calendar_service.py:26-27
• Real-time Sync: The system relies on manual or periodic polling rather than Webhooks (Push Notifications) from Google. Sources: COMPETITIVE_ANALYSIS.md:144-155
• Encryption: OAuth tokens are currently stored in plaintext, presenting a high-priority security risk noted for future migration. Sources: MISSING_INFO.md:7-13

The Calendar & Scheduling system provides the necessary infrastructure to transform raw recordings into context-aware meeting records by leveraging existing user schedules. Its integration with the database ensures that reminders and event metadata are readily available to the AI agents for generating summaries and action items.