Appwrite datetime attributes return UTC only: where should per-user timezone conversion live in a multi-region app?

Answer

Store each user's IANA timezone identifier (e.g., America/New_York) as a string attribute in their profile. Perform conversions to this zone at the point of use: use the browser's native API for UI display and retrieve the stored IANA zone for server-side logic in Appwrite Functions.

Confirmed Behavior

• Appwrite stores and returns all datetime attributes and system timestamps (like $createdAt) as ISO 8601 strings normalized to UTC.
• No per-document or per-user timezone metadata is natively attached to these timestamps.
• IANA identifiers are required to handle Daylight Saving Time (DST) transitions correctly; fixed numerical offsets are insufficient for long-term scheduling.

Architectural Explanation

Because Appwrite Functions execute in a server-side environment without access to the end-user's local device settings, they lack a request-level locale. Any logic that depends on a user's "today" (such as daily resets or region-specific scheduling) will fail if it relies on the server's system time. By storing the IANA zone in the user profile, you shift the responsibility of timezone context from the infrastructure to the data model, ensuring consistent behavior across different Appwrite Cloud or self-hosted regions.

Implementation Steps

1. Profile Modeling: Add a string attribute (e.g., timezone) to your user profile collection. Populate this during onboarding using Intl.DateTimeFormat().resolvedOptions().timeZone on the client.
2. Server-Side Conversion: In Appwrite Functions, fetch the user's IANA zone and use a library like Luxon or date-fns-tz to shift the UTC timestamp to the target zone before performing date-boundary calculations.
3. Date-Only Modeling: For birthdays, anniversaries, or fixed calendar dates, use a string attribute in YYYY-MM-DD format. This prevents the "date-shift" bug where a UTC-midnight timestamp is interpreted as the previous calendar day in western timezones.
4. Client-Side Display: Use the Intl API to format the UTC string returned by Appwrite into the user's current local time for the UI.

Verification

To verify this setup, create a test document with a UTC timestamp and a user profile set to Asia/Tokyo. Run a function to confirm that the UTC timestamp is correctly shifted to the Tokyo offset, and verify that a YYYY-MM-DD string remains unchanged regardless of the viewing region.