ADR-004: Unified Scheduling Strategy

Status: Accepted Date: December 17, 2025 Deciders: CODITECT Architecture Team

Context

CODITECT meeting integrations need robust scheduling capabilities that work consistently across providers (Google Meet, Zoom, future providers). Customers need:

• Unified scheduling interface regardless of provider
• Calendar synchronization with external systems
• Complex recurring meeting patterns
• Attendee management with invitations/RSVPs
• Availability checking across participants
• Pre-meeting reminder notifications

Decision

We will implement a MeetingSchedulerOrchestrator that provides:

1. Unified Scheduling Interface

class MeetingSchedulerOrchestrator:
    """Provider-agnostic meeting scheduler."""

    async def schedule_meeting(
        self,
        provider: str,
        title: str,
        start_time: datetime,
        duration: int,
        attendees: List[Attendee],
        recurrence: RecurrenceRule = None,
        reminders: List[Reminder] = None
    ) -> ScheduledMeeting

    async def check_availability(
        self,
        attendees: List[str],
        time_range: TimeRange,
        duration: int
    ) -> List[AvailableSlot]

    async def sync_calendar(
        self,
        calendar_id: str,
        direction: SyncDirection
    ) -> SyncResult

2. Calendar Sync Architecture

┌─────────────────────────────────────────────────────────────────┐
│                  MeetingSchedulerOrchestrator                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ CalendarSync    │  │ Availability    │  │ Reminder        │ │
│  │ Manager         │  │ Service         │  │ Service         │ │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘ │
│           │                    │                    │          │
└───────────┼────────────────────┼────────────────────┼──────────┘
            │                    │                    │
            ▼                    ▼                    ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│  Google Calendar  │ │  Microsoft Graph  │ │  Notification     │
│  API              │ │  API (Outlook)    │ │  Service          │
└───────────────────┘ └───────────────────┘ └───────────────────┘

3. Recurrence Pattern Support

Based on RFC 5545 (iCalendar) RRULE format:

@dataclass
class RecurrenceRule:
    frequency: Frequency  # DAILY, WEEKLY, MONTHLY, YEARLY
    interval: int = 1
    count: Optional[int] = None
    until: Optional[datetime] = None
    by_day: Optional[List[Weekday]] = None
    by_month_day: Optional[List[int]] = None
    by_month: Optional[List[int]] = None
    exceptions: List[datetime] = field(default_factory=list)

4. Attendee Management

@dataclass
class Attendee:
    email: str
    name: Optional[str] = None
    role: AttendeeRole = AttendeeRole.REQUIRED  # REQUIRED, OPTIONAL, ORGANIZER
    response_status: ResponseStatus = ResponseStatus.PENDING
    notify: bool = True

class AttendeeManager:
    async def invite_attendees(meeting_id: str, attendees: List[Attendee]) -> None
    async def update_rsvp(meeting_id: str, email: str, response: ResponseStatus) -> None
    async def send_update_notification(meeting_id: str) -> None
    async def get_attendee_responses(meeting_id: str) -> List[AttendeeResponse]

5. Availability Checking

class AvailabilityService:
    async def get_free_busy(
        self,
        calendars: List[str],
        time_min: datetime,
        time_max: datetime
    ) -> Dict[str, List[BusyPeriod]]

    async def find_available_slots(
        self,
        attendees: List[str],
        time_range: TimeRange,
        duration_minutes: int,
        working_hours: WorkingHours = None
    ) -> List[AvailableSlot]

6. Reminder System

@dataclass
class Reminder:
    minutes_before: int
    method: ReminderMethod  # EMAIL, PUSH, SMS, WEBHOOK

class ReminderService:
    async def schedule_reminder(meeting_id: str, reminder: Reminder) -> str
    async def cancel_reminder(reminder_id: str) -> None
    async def process_due_reminders() -> List[SentReminder]

Consequences

Positive

• Consistent scheduling experience across all providers
• Two-way calendar sync maintains data consistency
• Complex recurrence patterns handled uniformly
• Attendee management simplifies meeting coordination
• Availability checking reduces scheduling conflicts
• Reminder system improves meeting attendance

Negative

• Additional complexity in orchestration layer
• Calendar sync requires handling conflicts
• Must respect rate limits across multiple APIs
• Reminder system needs background job infrastructure

Neutral

• Some provider-specific features may not map to unified interface
• Calendar sync frequency must balance freshness vs API costs

Implementation Priority

Component	Priority	Complexity	Dependencies
Unified Scheduling	P0	Medium	Provider interfaces
Attendee Management	P0	Low	Provider interfaces
Recurrence Support	P1	Medium	Unified Scheduling
Calendar Sync	P1	High	External calendar APIs
Availability Checking	P1	Medium	Calendar Sync
Reminder System	P2	Medium	Notification service

References

• RFC 5545 (iCalendar specification)
• Google Calendar API freebusy endpoint
• Microsoft Graph calendar API
• ADR-001: Provider Abstraction Pattern