zarinpal-analytics-backend/docs/decisions/0004-source-timezone-normalization.md

ADR 0004: Interpret source timestamps as Asia/Tehran and normalize to UTC

• Status: Accepted
• Date: 2026-08-20

Context

The challenge archive contains timezone-naive timestamp strings such as 2026-01-02 11:52:56. It supplies no offset or timezone column. Analytics depend on consistent daily/hourly windows, retry durations, settlement timing, and period comparisons, so leaving interpretation implicit would make results environment-dependent.

Decision

Interpret every valid timezone-naive source timestamp as local civil time in the IANA Asia/Tehran zone. Convert canonical persisted timestamps to UTC-backed PostgreSQL timestamptz values. API contracts expose ISO-8601 timestamps with an explicit UTC offset (Z); merchant-facing presentation converts them to Asia/Tehran and uses the Jalali calendar.

The importer records the assumed zone and timezone-data/runtime version in its manifest. The raw archive remains immutable operational input identified by checksum, preserving the original textual values and allowing a new import version if authoritative source metadata later contradicts the assumption. A changed interpretation must never silently update an existing completed import.

Missing or invalid timestamp values remain missing/rejected according to the import validation policy; they are not replaced with import time. Timestamp-order anomalies are reported as data-quality evidence and are not automatically “corrected.”

Consequences

• Day/hour analytics have one documented merchant-relevant timezone.
• Database comparisons and API interchange use explicit instants rather than server-local time.
• The assumption is traceable and reversible through source checksum, immutable input, manifest metadata, and importer revision.
• Tests must cover conversion around relevant timezone-rule boundaries and ensure host/container timezone does not change results.
• Calendar conversion is a presentation concern; backend period boundaries are calculated from explicit Asia/Tehran local ranges and converted to UTC for querying.