25 lines
1.6 KiB
Markdown
25 lines
1.6 KiB
Markdown
# ADR 0009: Version reviewed Iranian calendar snapshots in Git
|
||
|
||
- Status: Accepted
|
||
- Date: 2026-08-20
|
||
|
||
## Context
|
||
|
||
Monthly, Persian-season, Nowruz, and public-holiday analytics need deterministic Gregorian/Jalali mappings and named date ranges. Runtime dependence on a public calendar API would add availability, version drift, and reproducibility risks. Official holiday dates can change across years, especially events derived from other calendars.
|
||
|
||
## Decision
|
||
|
||
Commit a reviewed, machine-readable calendar snapshot for every supported Jalali year. Use the Calendar Center of the University of Tehran Institute of Geophysics as the authoritative annual source (`https://calendar.ut.ac.ir/`). The source URL/document identity, retrieval date, checksum, reviewer, and snapshot schema version accompany each file.
|
||
|
||
For the challenge period, cover both Jalali 1404 and 1405 because Gregorian January–June 2026 crosses the Jalali year boundary. Runtime code reads validated database calendar tables populated from these versioned snapshots and never calls an external calendar API.
|
||
|
||
Differentiate official public holidays from analytical event/campaign windows. A Nowruz analytical window may extend beyond officially closed days, but its exact dates, rationale, and version are explicit rather than inferred by an LLM.
|
||
|
||
## Consequences
|
||
|
||
- Historical analytics are reproducible even if websites/APIs change.
|
||
- Annual calendar updates are reviewed source changes with validation tests.
|
||
- Unsupported years fail clearly instead of guessing holiday membership.
|
||
- Calendar data is committed reference data; raw payment archives remain ignored.
|
||
|