# 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
```bash
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
- [x] ICS parsing and sync (321 busy blocks from sample ICS)
- [x] Availability calculation
- [x] Participant CRUD operations
- [x] Frontend integration

## Next Steps
- [ ] Add background scheduler for periodic ICS sync
- [ ] Add calendar revocation mechanism