igny8/docs/00-SYSTEM/TIMEZONE.md

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