# Calendar Synchronization Architecture - Deep Analysis

## Executive Summary

This document provides a comprehensive architectural analysis of the calendar synchronization system, focusing on:
- **Agenda Widget** (Dashboard widget)
- **Agenda Page** (Full calendar view)
- **Courrier Page** (Email integration)
- **Calendar Synchronization Services** (Infomaniak CalDAV & Microsoft Graph API)

---

## 1. System Architecture Overview

### 1.1 Component Hierarchy

```
┌─────────────────────────────────────────────────────────────┐
│                    Dashboard (app/page.tsx)                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Calendar     │  │ News         │  │ Email        │      │
│  │ Widget       │  │ Widget       │  │ Widget       │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              Agenda Page (app/agenda/page.tsx)              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │         CalendarClient Component                     │   │
│  │  ┌──────────────┐  ┌─────────────────────────────┐  │   │
│  │  │ Calendar     │  │   FullCalendar (FullCalendar)│  │   │
│  │  │ Selector     │  │   - Month/Week/Day Views     │  │   │
│  │  │ (Sidebar)    │  │   - Event Creation/Edit     │  │   │
│  │  └──────────────┘  └─────────────────────────────┘  │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│         Courrier Page (app/courrier/page.tsx)               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Email        │  │ Email        │  │ Email        │      │
│  │ Sidebar      │  │ List         │  │ Detail       │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│         Calendar Sync Services                              │
│  ┌──────────────────────┐  ┌──────────────────────┐       │
│  │ Infomaniak CalDAV    │  │ Microsoft Graph API   │       │
│  │ Sync Service         │  │ Sync Service          │       │
│  └──────────────────────┘  └──────────────────────┘       │
└─────────────────────────────────────────────────────────────┘
```

---

## 2. Agenda Widget Analysis

### 2.1 Component Location
- **File**: `components/calendar.tsx`
- **Usage**: Dashboard widget showing upcoming 7 events
- **Type**: Client Component (`"use client"`)

### 2.2 Key Features

#### Data Fetching
```typescript
// Fetches from /api/calendars?refresh=true
// Bypasses cache with refresh=true parameter
const response = await fetch('/api/calendars?refresh=true');
```

#### Event Processing
1. **Extracts events** from all calendars
2. **Filters** for upcoming events (from today onwards)
3. **Sorts** by start date
4. **Limits** to 7 events
5. **Maps** calendar color and name to each event

#### Refresh Mechanism
- **Manual refresh** only via button click
- **No automatic polling** or unified refresh integration
- **Fetches on mount** only

### 2.3 Issues Identified

1. **❌ No Unified Refresh Integration**
   - Not using `useUnifiedRefresh` hook
   - Manual refresh only
   - No automatic background updates

2. **❌ Cache Bypass**
   - Always uses `?refresh=true` parameter
   - Bypasses Redis cache every time
   - May cause unnecessary database load

3. **❌ No Error Recovery**
   - Basic error handling
   - No retry mechanism
   - No offline state handling

4. **⚠️ Date Filtering Logic**
   - Filters events from "start of day" (00:00:00)
   - May miss events happening later today if fetched early morning

### 2.4 Data Flow

```
User Dashboard
    │
    ├─> Calendar Widget (components/calendar.tsx)
    │       │
    │       ├─> useEffect() triggers on mount
    │       │
    │       ├─> fetch('/api/calendars?refresh=true')
    │       │       │
    │       │       ├─> API Route (app/api/calendars/route.ts)
    │       │       │       │
    │       │       │       ├─> Checks Redis cache (skipped if refresh=true)
    │       │       │       │
    │       │       │       ├─> Prisma: Calendar.findMany()
    │       │       │       │       └─> Include: events (ordered by start)
    │       │       │       │
    │       │       │       └─> Cache result in Redis
    │       │       │
    │       │       └─> Returns: Calendar[] with events[]
    │       │
    │       ├─> Process events:
    │       │       ├─> flatMap all calendars.events
    │       │       ├─> Filter: start >= today (00:00:00)
    │       │       ├─> Sort by start date
    │       │       └─> Slice(0, 7)
    │       │
    │       └─> Render: Card with event list
```

---

## 3. Agenda Page Analysis

### 3.1 Component Location
- **File**: `app/agenda/page.tsx` (Server Component)
- **Client Component**: `components/calendar/calendar-client.tsx`
- **Route**: `/agenda`

### 3.2 Server-Side Logic (page.tsx)

#### Auto-Setup Calendar Sync

The page automatically sets up calendar synchronization for email accounts:

1. **Infomaniak Accounts** (CalDAV)
   - Discovers calendars using `discoverInfomaniakCalendars()`
   - Creates "Privée" calendar if not exists
   - Creates `CalendarSync` record with:
     - `provider: 'infomaniak'`
     - `syncFrequency: 15` minutes
     - `externalCalendarUrl` from discovery
   - Triggers initial sync

2. **Microsoft Accounts** (OAuth)
   - Discovers calendars using `discoverMicrosoftCalendars()`
   - Creates "Privée" calendar if not exists
   - Creates `CalendarSync` record with:
     - `provider: 'microsoft'`
     - `syncFrequency: 5` minutes (more reactive)
     - `externalCalendarId` from Graph API
   - Triggers initial sync

#### Calendar Filtering Logic

```typescript
// Excludes "Privée" and "Default" calendars that are NOT synced
calendars = calendars.filter(cal => {
  const isPrivateOrDefault = cal.name === "Privée" || cal.name === "Default";
  const hasActiveSync = cal.syncConfig?.syncEnabled === true && 
                        cal.syncConfig?.mailCredential;
  
  // Exclude "Privée"/"Default" calendars that are not actively synced
  if (isPrivateOrDefault && !hasActiveSync) {
    return false;
  }
  return true;
});
```

#### Background Sync Trigger

For Microsoft calendars, the page triggers background sync if needed:
- Checks if sync is needed (2 minutes minimum interval)
- Triggers async sync (doesn't block page load)
- Sync runs in background, updates database
- Next page load will show synced events

### 3.3 Client-Side Component (calendar-client.tsx)

#### Key Features

1. **FullCalendar Integration**
   - Uses `@fullcalendar/react` library
   - Views: Month, Week, Day
   - Plugins: dayGrid, timeGrid, interaction

2. **Calendar Management**
   - Calendar selector sidebar (left column)
   - Visibility toggle per calendar
   - Calendar creation/editing dialog
   - Sync configuration UI

3. **Event Management**
   - Create events by clicking/selecting dates
   - Edit events by clicking on them
   - Delete events
   - Event form with:
     - Title, description, location
     - Start/end date and time
     - All-day toggle
     - Calendar selection

4. **Data Refresh**
   - `fetchCalendars()` function
   - Calls `/api/calendars` (no refresh parameter)
   - Uses Redis cache by default
   - Updates FullCalendar via `calendarApi.refetchEvents()`

#### Calendar Display Logic

```typescript
// Sorts calendars: synced first, then groups, then missions
const sortCalendars = (cals) => {
  return [...filtered].sort((a, b) => {
    const aIsSynced = a.syncConfig?.syncEnabled && a.syncConfig?.mailCredential;
    const bIsSynced = b.syncConfig?.syncEnabled && b.syncConfig?.mailCredential;
    
    // Synced calendars first
    if (aIsSynced && !bIsSynced) return -1;
    if (!aIsSynced && bIsSynced) return 1;
    
    // Then groups, then missions, then by name
    // ...
  });
};
```

#### Event Rendering

Events are mapped to FullCalendar format:
```typescript
events={calendars.flatMap(cal => 
  cal.events.map(event => ({
    id: event.id,
    title: event.title,
    start: new Date(event.start),
    end: new Date(event.end),
    allDay: event.isAllDay,
    backgroundColor: `${cal.color}dd`,
    borderColor: cal.color,
    extendedProps: {
      calendarName: cal.name,
      location: event.location,
      description: cleanDescription(event.description),
      calendarId: event.calendarId,
      originalEvent: event,
      color: cal.color
    }
  }))
)}
```

### 3.4 Issues Identified

1. **⚠️ Sync Timing**
   - Microsoft sync triggers on page load (background)
   - May cause delay before events appear
   - No loading indicator for background sync

2. **⚠️ Calendar Filtering Complexity**
   - Complex logic for "Privée"/"Default" calendars
   - May hide calendars that should be visible
   - Logging is extensive but may be confusing

3. **❌ No Real-Time Updates**
   - Events only update on manual refresh
   - No WebSocket or polling for new events
   - User must refresh to see synced events

4. **⚠️ Event Matching Logic**
   - Infomaniak: Matches by title + start date (within 1 minute)
   - Microsoft: Matches by `[MS_ID:xxx]` in description
   - May create duplicates if matching fails

---

## 4. Courrier Page Analysis

### 4.1 Component Location
- **File**: `app/courrier/page.tsx`
- **Route**: `/courrier`
- **Type**: Client Component

### 4.2 Key Features

#### Email Account Management
- Multiple email account support
- Account colors for visual distinction
- Account settings (display name, password, color)

#### Email Operations
- Folder navigation (INBOX, Sent, Drafts, etc.)
- Email reading, composing, replying
- Email search
- Bulk operations (delete, mark read/unread)

#### Integration with Calendar Sync

The Courrier page is **indirectly** related to calendar sync:

1. **Email Accounts** are stored in `MailCredentials` table
2. **Calendar Sync** uses `MailCredentials` for authentication
3. **Auto-Setup** in Agenda page discovers accounts from Courrier

### 4.3 Connection to Calendar Sync

```typescript
// In agenda/page.tsx:
const infomaniakAccounts = await prisma.mailCredentials.findMany({
  where: {
    userId: session?.user?.id || '',
    host: { contains: 'infomaniak' },
    password: { not: null }
  }
});

// For each account, create calendar sync
for (const account of infomaniakAccounts) {
  // Discover calendars
  const calendars = await discoverInfomaniakCalendars(account.email, account.password!);
  
  // Create calendar and sync config
  // ...
}
```

### 4.4 Issues Identified

1. **⚠️ No Direct Calendar Integration**
   - Courrier page doesn't show calendar events
   - No email-to-calendar event creation
   - Separate systems (email vs calendar)

2. **⚠️ Account Deletion Impact**
   - Deleting email account may orphan calendar sync
   - Agenda page has cleanup logic, but may miss edge cases

---

## 5. Calendar Synchronization Services

### 5.1 Infomaniak CalDAV Sync

#### Service Location
- **File**: `lib/services/caldav-sync.ts`

#### Key Functions

1. **`discoverInfomaniakCalendars(email, password)`**
   - Uses WebDAV client (`webdav` library)
   - Connects to `https://sync.infomaniak.com`
   - Lists directories using `PROPFIND`
   - Extracts calendar name and color from XML

2. **`fetchCalDAVEvents(email, password, calendarUrl, startDate, endDate)`**
   - Uses `REPORT` method with `calendar-query`
   - Filters events by date range
   - Parses iCalendar format (`.ics`)
   - Returns `CalDAVEvent[]`

3. **`syncInfomaniakCalendar(calendarSyncId, forceSync)`**
   - Fetches events from CalDAV (1 month ago to 3 months ahead)
   - Gets existing events from database
   - Matches events by title + start date (within 1 minute)
   - Creates new events or updates existing
   - Updates `lastSyncAt` timestamp

#### Event Matching Logic

```typescript
// Tries to find existing event by:
const existingEvent = existingEvents.find(
  (e) =>
    e.title === caldavEvent.summary &&
    Math.abs(new Date(e.start).getTime() - caldavEvent.start.getTime()) < 60000
);
```

**Issue**: This matching is fragile:
- May create duplicates if title changes
- May miss events if timezone conversion causes >1 minute difference
- No UID-based matching (iCalendar has UID field)

### 5.2 Microsoft Graph API Sync

#### Service Location
- **File**: `lib/services/microsoft-calendar-sync.ts`

#### Key Functions

1. **`discoverMicrosoftCalendars(userId, email)`**
   - Uses Microsoft Graph API
   - Endpoint: `https://graph.microsoft.com/v1.0/me/calendars`
   - Requires OAuth token with calendar scope
   - Returns `MicrosoftCalendar[]`

2. **`fetchMicrosoftEvents(userId, email, calendarId, startDate, endDate)`**
   - Endpoint: `https://graph.microsoft.com/v1.0/me/calendars/{calendarId}/events`
   - Filters by date range using `$filter` parameter
   - Returns `MicrosoftEvent[]`

3. **`syncMicrosoftCalendar(calendarSyncId, forceSync)`**
   - Fetches events (1 month ago to 6 months ahead)
   - Converts Microsoft events to CalDAV-like format
   - **Stores Microsoft ID in description**: `[MS_ID:xxx]`
   - Matches events by Microsoft ID first, then by title+date
   - Creates/updates events in database

#### Event Matching Logic

```typescript
// First: Match by Microsoft ID in description
let existingEvent = existingEvents.find((e) => {
  if (e.description && e.description.includes(`[MS_ID:${microsoftId}]`)) {
    return true;
  }
  return false;
});

// Fallback: Match by title + start date
if (!existingEvent) {
  existingEvent = existingEvents.find(
    (e) =>
      e.title === caldavEvent.summary &&
      Math.abs(new Date(e.start).getTime() - caldavEvent.start.getTime()) < 60000
  );
}
```

**Better than Infomaniak**: Uses ID-based matching, but stores ID in description (hacky)

### 5.3 Sync Job Service

#### Service Location
- **File**: `lib/services/calendar-sync-job.ts`

#### Function: `runCalendarSyncJob()`

- Gets all enabled sync configurations
- Checks if sync is needed (based on `syncFrequency`)
- Calls appropriate sync function based on provider
- Logs results (successful, failed, skipped)

**Usage**: Should be called by cron job or scheduled task

### 5.4 Issues Identified

1. **❌ No UID-Based Matching for Infomaniak**
   - Should use iCalendar UID field
   - Current matching is fragile

2. **⚠️ Microsoft ID Storage**
   - Stores ID in description field (hacky)
   - Should use dedicated `externalEventId` field in Event model

3. **❌ No Event Deletion**
   - Sync only creates/updates events
   - Doesn't delete events removed from external calendar
   - May show stale events

4. **⚠️ Error Handling**
   - Errors are logged but sync continues
   - May leave calendar in inconsistent state
   - No retry mechanism for transient failures

5. **⚠️ Sync Frequency**
   - Infomaniak: 15 minutes (may be too slow)
   - Microsoft: 5 minutes (better, but still not real-time)
   - No user-configurable frequency

6. **❌ No Incremental Sync**
   - Always fetches full date range
   - May be slow for calendars with many events
   - Should use `lastSyncAt` to fetch only changes

---

## 6. API Routes Analysis

### 6.1 `/api/calendars` (GET)

**File**: `app/api/calendars/route.ts`

#### Features
- Redis caching (unless `?refresh=true`)
- Returns calendars with events
- Events ordered by start date

#### Issues
- Cache TTL not specified (uses default)
- No cache invalidation on event creation/update
- `refresh=true` bypasses cache (used by widget)

### 6.2 `/api/calendars/sync` (POST, PUT, GET, DELETE)

**File**: `app/api/calendars/sync/route.ts`

#### Features
- **POST**: Create sync configuration
- **PUT**: Trigger manual sync
- **GET**: Get sync status
- **DELETE**: Remove sync configuration

#### Issues
- Manual sync triggers full sync (not incremental)
- No webhook support for real-time updates

---

## 7. Database Schema

### 7.1 Calendar Model

```prisma
model Calendar {
  id          String   @id @default(uuid())
  name        String
  color       String
  description String?
  userId      String
  missionId   String?
  events      Event[]
  syncConfig  CalendarSync?
  // ...
}
```

### 7.2 CalendarSync Model

```prisma
model CalendarSync {
  id                  String   @id @default(uuid())
  calendarId         String   @unique
  mailCredentialId   String?
  provider           String   // "infomaniak" | "microsoft"
  externalCalendarId String?
  externalCalendarUrl String?
  syncEnabled        Boolean  @default(true)
  lastSyncAt         DateTime?
  syncFrequency      Int      @default(15) // minutes
  lastSyncError      String?
  // ...
}
```

### 7.3 Event Model

```prisma
model Event {
  id          String   @id @default(uuid())
  title       String
  description String?
  start       DateTime
  end         DateTime
  location    String?
  isAllDay    Boolean  @default(false)
  calendarId  String
  userId      String
  // ...
}
```

**Missing Fields**:
- `externalEventId` (for reliable matching)
- `externalEventUrl` (for linking to external calendar)
- `lastSyncedAt` (for incremental sync)

---

## 8. Critical Issues Summary

### 8.1 High Priority

1. **Event Matching Fragility**
   - Infomaniak: No UID-based matching
   - Microsoft: ID stored in description (hacky)
   - **Impact**: Duplicate events, missed updates

2. **No Event Deletion**
   - Removed events stay in database
   - **Impact**: Stale events shown to users

3. **No Real-Time Updates**
   - Widget and page don't auto-refresh
   - **Impact**: Users must manually refresh to see new events

### 8.2 Medium Priority

4. **Cache Invalidation**
   - Events created/updated don't invalidate cache
   - **Impact**: Stale data shown until cache expires

5. **Sync Frequency**
   - Infomaniak: 15 minutes (too slow)
   - **Impact**: Delayed event appearance

6. **No Incremental Sync**
   - Always fetches full date range
   - **Impact**: Slow sync, unnecessary API calls

### 8.3 Low Priority

7. **Widget Refresh Integration**
   - Not using unified refresh system
   - **Impact**: Inconsistent refresh behavior

8. **Error Recovery**
   - No retry mechanism
   - **Impact**: Sync failures require manual intervention

---

## 9. Recommendations

### 9.1 Immediate Fixes

1. **Add `externalEventId` field to Event model**
   ```prisma
   model Event {
     // ... existing fields
     externalEventId  String?  // UID from iCalendar or Microsoft ID
     externalEventUrl String?  // Link to external calendar event
   }
   ```

2. **Implement UID-based matching for Infomaniak**
   - Use iCalendar UID field for matching
   - Store in `externalEventId`

3. **Implement event deletion**
   - Compare external events with database events
   - Delete events not in external calendar

4. **Add cache invalidation**
   - Invalidate Redis cache on event create/update/delete
   - Invalidate on sync completion

### 9.2 Short-Term Improvements

5. **Implement incremental sync**
   - Use `lastSyncAt` to fetch only changes
   - Use CalDAV `sync-token` for Infomaniak
   - Use Microsoft Graph delta queries

6. **Add real-time updates**
   - WebSocket or Server-Sent Events
   - Notify clients when sync completes
   - Auto-refresh widget and page

7. **Improve error handling**
   - Retry mechanism for transient failures
   - Better error messages for users
   - Sync status indicator in UI

### 9.3 Long-Term Enhancements

8. **Unified refresh system integration**
   - Use `useUnifiedRefresh` hook in widget
   - Consistent refresh behavior across app

9. **User-configurable sync frequency**
   - Allow users to set sync interval
   - Different frequencies per calendar

10. **Two-way sync**
    - Sync local events to external calendars
    - Handle conflicts (last-write-wins or user choice)

---

## 10. Testing Recommendations

### 10.1 Unit Tests
- Event matching logic (UID-based, title+date fallback)
- Date range filtering
- iCalendar parsing
- Microsoft event conversion

### 10.2 Integration Tests
- Full sync flow (discover → sync → verify)
- Event creation/update/deletion
- Cache invalidation
- Error recovery

### 10.3 E2E Tests
- Widget displays events correctly
- Page shows synced events
- Manual sync triggers correctly
- Calendar creation/editing

---

## 11. Conclusion

The calendar synchronization system is **functional but has several architectural issues** that impact reliability and user experience:

1. **Fragile event matching** may cause duplicates or missed updates
2. **No event deletion** leaves stale events in the database
3. **No real-time updates** requires manual refresh
4. **Cache invalidation** is missing, causing stale data

**Priority**: Focus on fixing event matching and deletion first, as these directly impact data integrity. Then implement cache invalidation and real-time updates for better UX.

---

**Document Version**: 1.0  
**Last Updated**: 2025-01-XX  
**Author**: Senior Software Architect Analysis