---
phase: 18-auto-timezone-detection-and-ability-to-change-timezone
plan: "01"
subsystem: api
tags: [timezone, iana, drizzle, vitest, tdd]

# Dependency graph
requires:
  - phase: 10-admin-role-settings
    provides: appConfig table (key/value store where household_timezone key lives)
provides:
  - getHouseholdTimezone(db) — single D-05 accessor for stored household timezone with D-06 fallback chain
  - isValidIanaTimezone(tz) — IANA timezone validator via Intl.DateTimeFormat try/catch

affects:
  - 18-02-PLAN (broker rewire — reminderScheduler + outboxWorker import getHouseholdTimezone)
  - 18-03-PLAN (admin API routes — import isValidIanaTimezone for Zod refine)
  - 18-04-PLAN (PWA settings UI — consumes admin timezone API built on top of these)

# Tech tracking
tech-stack:
  added: []
  patterns:
    - Drizzle single-row PK lookup (.select().from().where(eq()).limit(1)) — same pattern as requireAdmin.ts
    - IANA timezone validation via try/catch on Intl.DateTimeFormat (avoids Intl.supportedValuesOf omitting 'UTC')
    - TZ env save/restore in beforeEach/afterEach to prevent env state leaks between tests

key-files:
  created:
    - apps/api/src/lib/householdTimezone.ts
    - apps/api/tests/lib/householdTimezone.test.ts
  modified: []

key-decisions:
  - "isValidIanaTimezone uses Intl.DateTimeFormat try/catch — NOT Intl.supportedValuesOf (omits UTC per RESEARCH Pitfall 2)"
  - "D-06 fallback chain verbatim: row?.value ?? process.env.TZ ?? Intl.DateTimeFormat().resolvedOptions().timeZone"
  - "Literal key string 'household_timezone' in the WHERE clause (D-01)"

patterns-established:
  - "householdTimezone accessor pattern: getHouseholdTimezone(db) as the single import site for all tz reads in broker workers"

requirements-completed: [D-05, D-06]

# Metrics
duration: 2min
completed: 2026-06-15
---

# Phase 18 Plan 01: Household Timezone Accessor + IANA Validator Summary

**Single D-05 accessor `getHouseholdTimezone(db)` reads `household_timezone` from `app_config` with D-06 fallback chain; `isValidIanaTimezone(tz)` validates via `Intl.DateTimeFormat` try/catch (not `supportedValuesOf`)**

## Performance

- **Duration:** 2 min
- **Started:** 2026-06-15T02:04:31Z
- **Completed:** 2026-06-15T02:06:50Z
- **Tasks:** 2 (TDD RED + GREEN)
- **Files modified:** 2

## Accomplishments

- Created `apps/api/src/lib/householdTimezone.ts` exporting `getHouseholdTimezone` and `isValidIanaTimezone`
- 11 unit tests cover all 6 required behaviors: stored row, no-row + TZ env, no-row + no-TZ, null row, valid zones, invalid zones
- D-06 fallback chain `row?.value ?? process.env.TZ ?? Intl.DateTimeFormat().resolvedOptions().timeZone` reproduced verbatim
- TypeScript typecheck (`tsc --noEmit`) clean; full 358-test suite green with no regressions
- TDD gate compliance: RED commit (`db0077c`) precedes GREEN commit (`eaceff0`)

## Task Commits

1. **Task 1: RED — failing unit tests** - `db0077c` (test)
2. **Task 2: GREEN — implement accessor + validator** - `eaceff0` (feat)

**Plan metadata:** (see final docs commit below)

## Files Created/Modified

- `apps/api/src/lib/householdTimezone.ts` — D-05 accessor + IANA validator, exported for broker + admin route consumers
- `apps/api/tests/lib/householdTimezone.test.ts` — 11 unit tests for fallback chain and validator

## Decisions Made

- `isValidIanaTimezone` uses `Intl.DateTimeFormat(undefined, { timeZone: tz })` try/catch — `Intl.supportedValuesOf('timeZone')` was explicitly avoided because it omits `'UTC'` in some environments (RESEARCH Pitfall 2).
- Fallback chain matches the verbatim expression found at `reminderScheduler.ts:247` so the all-day reminder path continues to work unchanged before Plan 02 seeds a stored value.
- `db` is accepted as a parameter (not imported from `db/client.js`) to enable clean mock-based unit testing without a live MariaDB connection.

## Deviations from Plan

None — plan executed exactly as written.

## Issues Encountered

- The vitest global setup requires a MariaDB connection (`global-setup.ts`). Tests need to be run with `DB_HOST=127.0.0.1` when running locally (the `.env` sets `DB_HOST=mariadb` for Docker networking). This is a known dev environment pattern documented in `familysync-dev-stack-setup.md` and has no effect on CI (which uses the service container).

## Known Stubs

None — this plan creates a pure utility module with no UI stubs or placeholder data.

## Threat Flags

None — no new network endpoints, auth paths, file access patterns, or schema changes were introduced. The accessor is a read-only DB lookup within the trusted server process (T-18-01 disposition: accept).

## TDD Gate Compliance

- RED gate: `db0077c` — `test(18-01): add failing tests for household timezone accessor + IANA validator`
- GREEN gate: `eaceff0` — `feat(18-01): implement household timezone accessor + IANA validator`
- REFACTOR gate: N/A (implementation was clean on first pass)

## Next Phase Readiness

- `getHouseholdTimezone` and `isValidIanaTimezone` are the foundation both Plan 18-02 (broker rewire) and Plan 18-03 (admin API + Zod refine) consume.
- Plan 18-02 can import `getHouseholdTimezone` from `../lib/householdTimezone.js` to replace the bare `process.env.TZ ?? Intl…` lookups in `reminderScheduler.ts:247` and `outboxWorker.ts:501,607`.
- Plan 18-03 can import `isValidIanaTimezone` for the Zod `.refine()` on `PUT /api/admin/config/timezone`.

## Self-Check: PASSED

- `apps/api/src/lib/householdTimezone.ts` — FOUND
- `apps/api/tests/lib/householdTimezone.test.ts` — FOUND
- Commit `db0077c` — FOUND
- Commit `eaceff0` — FOUND

---
*Phase: 18-auto-timezone-detection-and-ability-to-change-timezone*
*Completed: 2026-06-15*