common-availability/PLAN.md

Common Availability - Implementation Plan

Project Overview

ICS-based calendar availability coordination system. Company members submit ICS URLs, and the system continuously syncs and calculates common availability for scheduling meetings.

Architecture

Backend (FastAPI + PostgreSQL)

• Models: Participant (id, name, email, ics_url) and BusyBlock (participant_id, start_time, end_time)
• Services: ICS fetching/parsing via icalendar library, availability calculation
• API Endpoints:
  • POST /api/participants - Add participant with ICS URL (auto-syncs)
  • GET /api/participants - List all participants
  • DELETE /api/participants/{id} - Remove participant
  • POST /api/availability - Calculate availability for given participants
  • POST /api/sync - Sync all calendars
  • POST /api/sync/{id} - Sync specific participant

Frontend (React + TypeScript)

• Existing UI preserved (React, Vite, shadcn-ui)
• API client in src/api/client.ts
• Real-time availability from backend (replaces mock data)

Current State

Implementation complete and tested. All systems operational.

How to Run

just fresh     # Build, start containers, run migrations
just up        # Start services
just logs      # View logs
just migrate   # Run Alembic migrations
just sync-calendars  # Sync all ICS feeds

Access:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API docs: http://localhost:8000/docs

Test Flow

1. Add participant with ICS URL (e.g., https://user.fm/freebusy/v1-.../Calendar.ics)
2. Select participants in Schedule tab
3. View availability heatmap (green = all free, yellow = partial, red = busy)
4. Click sync button to refresh calendars

Verified Working

• ICS parsing and sync (321 busy blocks from sample ICS)
• Availability calculation
• Participant CRUD operations
• Frontend integration

Next Steps

• Add background scheduler for periodic ICS sync
• Add calendar revocation mechanism