church-api/TIMEZONE_MIGRATION_PLAN.md

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