zarinpal-analytics-backend/docs/decisions/0012-iranian-reporting-week.md

ADR 0012: Use Saturday-through-Friday reporting weeks

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

Context

Weekly analytics require one boundary shared by PostgreSQL grouping, API filters, cache keys, comparisons, and Persian UI labels.

Decision

Use the Iranian week in Asia/Tehran: Saturday is the first day and Friday is the last day. Store the Tehran-local Saturday date as the stable week key. API and query ranges use a half-open interval from Saturday 00:00 inclusive to the following Saturday 00:00 exclusive.

Consequences

• Week boundaries remain correct and unambiguous across daylight/timezone handling.
• A week crossing a Jalali month or year remains identified by its starting Saturday date.
• Previous-period comparison uses the immediately preceding Saturday-through-Friday interval.