# Timezone Standard

## Purpose
This document defines the single-source timezone standard for IGNY8 and how all future time-related features must use it.

## Single Source of Truth
- **Account timezone** is the canonical timezone for all user-visible times and scheduling UI.
- The value is stored on the Account model as `account_timezone` (IANA name, e.g., `America/New_York`).
- Selection modes:
  - **Country-derived**: timezone is derived from billing country.
  - **Manual**: user picks an IANA timezone that maps to a UTC offset list.

## Storage Rules
- **Persist timestamps in UTC** in the database.
- **Never store local times** without timezone context.
- Store user selection in `Account.account_timezone` and (when needed) `timezone_mode` and `timezone_offset` for UI display.

## Display Rules (Frontend)
- All UI formatting must use the account timezone.
- Use shared helpers:
  - `getAccountTimezone()` for the active timezone.
  - `formatDate()`, `formatDateTime()`, `formatRelativeDate()` for consistent formatting.
- **Do not** call `toLocaleDateString()` or `toLocaleTimeString()` without passing the account timezone.

## Scheduling Rules
- All scheduling inputs in UI are **account timezone**.
- Convert to UTC before sending to the backend.
- All API payloads for scheduling must send ISO-8601 with timezone offset.
- The backend stores scheduled datetimes in UTC.

## Backend API Contract
- Endpoints that return timestamps should return UTC ISO strings.
- Endpoints that return “server time” should return **account-local time** for display, plus the account timezone identifier.
- If the account timezone is invalid or missing, fall back to `UTC`.

## Country List Source
- Country list must be fetched from `/v1/auth/countries/`.
- No hardcoded country lists in UI or backend responses.

## Implementation Checklist (New Features)
1. **Input**: confirm user inputs are in account timezone.
2. **Conversion**: convert to UTC before persistence or scheduling.
3. **Storage**: store in UTC only.
4. **Output**: format all timestamps with account timezone helpers.
5. **API**: ensure responses include timezone-aware context when needed.

## Guardrails
- Never introduce a second timezone source per user/site.
- Do not mix server timezone with account timezone in UI.
- Avoid timezone math in the UI; prefer helpers and backend-provided values when possible.

## Examples
- **Display date in UI**:
  - Use `formatDateTime(timestamp)` to render in account timezone.
- **Schedule content**:
  - User selects date/time in account timezone → convert to ISO → send to `/schedule/`.

## Troubleshooting
- If times appear “off”:
  - Check account timezone is set.
  - Confirm UI uses helpers.
  - Confirm backend converts to UTC before save.

---
Owner: Platform
Last updated: 2026-01-19