# Timezone Migration Plan: V1/V2 Endpoints

## Problem Statement
Currently, the database stores EST times that are masquerading as UTC. This causes confusion and requires hacky workarounds on the frontend to display proper times on devices.

## Solution Overview
- **Database**: Store actual UTC times (fix the current EST-masquerading-as-UTC issue)
- **V1 Endpoints**: Convert UTC → EST for backward compatibility with existing clients
- **V2 Endpoints**: Return actual UTC times and let clients handle timezone conversion

## Current State
- Database columns: `TIMESTAMP WITH TIME ZONE` (should store UTC but currently stores EST)
- V1 endpoints: `/api/events`, `/api/bulletins`, etc. - return EST times masquerading as UTC
- V2 endpoints: `/api/v2/events`, `/api/v2/bulletins`, etc. - already exist but may have same timezone issues

## Target State
- **Database**: Store true UTC times
- **V1 Endpoints**: Return EST times (for backward compatibility)
- **V2 Endpoints**: Return true UTC times (clients handle conversion)

## Implementation Steps

### Step 1: Database Migration
1. Identify all datetime fields that currently store EST-masquerading-as-UTC
2. Convert existing EST times to actual UTC times
3. Ensure all new inserts store proper UTC times

**Key tables/fields to migrate**:
- `events.start_time`, `events.end_time`
- `pending_events.start_time`, `pending_events.end_time`, `pending_events.submitted_at`
- `bulletins.created_at`, `bulletins.updated_at`
- Other timestamp fields

### Step 2: V1 Endpoint Modification
1. Read UTC times from database
2. Add conversion layer: UTC → EST
3. Return EST times to maintain backward compatibility
4. Existing frontend clients continue working without changes

**Endpoints to modify**:
- `/api/events*`
- `/api/bulletins*`
- `/api/schedule*`
- All other v1 endpoints returning datetime fields

### Step 3: V2 Endpoint Verification
1. Ensure v2 endpoints read UTC from database
2. Return true UTC times without conversion
3. Remove any existing timezone conversion logic
4. Let clients handle timezone conversion based on their needs

**V2 endpoints**:
- `/api/v2/events*`
- `/api/v2/bulletins*`
- `/api/v2/schedule*`
- All other v2 endpoints

### Step 4: Utility Functions
Create conversion utilities in `src/utils/datetime.rs`:

1. `convert_utc_to_est()` - For v1 endpoints
2. `ensure_utc_storage()` - For database inserts
3. `migrate_est_to_utc()` - For data migration

## Migration Strategy

### Phase 1: Database Migration (No Breaking Changes)
- Run migration to convert EST → UTC in database
- Update insert/update logic to store UTC
- Deploy without changing endpoint behavior

### Phase 2: V1 Endpoint Compatibility Layer
- Add UTC → EST conversion to v1 endpoints
- Deploy and verify existing clients still work
- No frontend changes needed

### Phase 3: V2 Endpoint Cleanup
- Ensure v2 endpoints return proper UTC
- Deploy and test with v2-compatible clients
- Update documentation for v2 API

### Phase 4: Client Migration
- Frontend applications gradually migrate to v2 endpoints
- V2 clients handle timezone conversion locally
- Better user experience with proper timezone handling

### Phase 5: V1 Deprecation (Future)
- Announce v1 deprecation timeline
- Eventually remove v1 endpoints after all clients migrate

## Benefits
- **Clean separation**: Database stores UTC, display logic in clients
- **Backward compatibility**: V1 clients continue working
- **Future-proof**: V2 clients get proper UTC handling
- **No more hacks**: Eliminates workarounds for timezone display

## Files to Modify
- `src/utils/datetime.rs` - Add conversion utilities
- `src/handlers/*.rs` - V1 endpoints add EST conversion
- `src/handlers/v2/*.rs` - Verify UTC handling
- `migrations/` - Database migration script
- `src/db/*.rs` - Ensure UTC storage on inserts

## Testing Strategy
- Unit tests for conversion utilities
- Integration tests comparing v1 vs v2 responses
- Verify v1 returns EST times
- Verify v2 returns UTC times
- Test database migration with sample data