starcoach-hackathon/zarinpal-analytics-deployment
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: define analytics refresh operations

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 15:59:21 +03:30
parent cf68517b3a
commit 16245e5c0b
2 changed files with 5 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
AGENTS.md
View File

@@ -29,6 +29,8 @@ This repository owns deployment concerns only. Backend and frontend directories
- Everything runs through Docker, Docker Compose, Bash scripts, and environment files/templates. - Everything runs through Docker, Docker Compose, Bash scripts, and environment files/templates.
- The CSV-to-PostgreSQL workflow is a one-time administrative bootstrap/recovery command, never a scheduled ingestion service. ZarinPal owns future production payment writes. - The CSV-to-PostgreSQL workflow is a one-time administrative bootstrap/recovery command, never a scheduled ingestion service. ZarinPal owns future production payment writes.
- The analytics refresh worker is not an ingestion service: it derives projections from normalized PostgreSQL changes, publishes within 15 minutes, and performs an idempotent nightly reconciliation. Deployment must surface failed/stale refreshes and must not advance freshness on failure.
- Reviewed yearly Iranian calendar snapshots are versioned backend reference data and loaded into PostgreSQL; production containers must not depend on a runtime calendar API.
- Nginx is the only public entry point. PostgreSQL and internal services are not internet-exposed. - Nginx is the only public entry point. PostgreSQL and internal services are not internet-exposed.
- Health checks distinguish liveness from readiness. - Health checks distinguish liveness from readiness.
- Backups are encrypted where supported, validated, retention-aware, and paired with rehearsed restores. - Backups are encrypted where supported, validated, retention-aware, and paired with rehearsed restores.

4
CAPABILITY-MAP.md
View File

@@ -15,7 +15,7 @@ The hackathon demo will seed one account per merchant. Where merchant profile fi
|---:|---|---|---|:---:| |---:|---|---|---|:---:|
| 1 | Data foundation | PostgreSQL model, one-time CSV bootstrap, provenance, validation, quality reporting, synthetic merchant profiles; future source writes are owned by ZarinPal | — | Yes | | 1 | Data foundation | PostgreSQL model, one-time CSV bootstrap, provenance, validation, quality reporting, synthetic merchant profiles; future source writes are owned by ZarinPal | — | Yes |
| 2 | Identity and access | Merchant credentials, sessions, tenant isolation, demo account seeding | Data foundation | Yes | | 2 | Identity and access | Merchant credentials, sessions, tenant isolation, demo account seeding | Data foundation | Yes |
| 3 | Analytics engine | Deterministic metrics, cohorts, trends, diagnostic drill-downs, traceability | Data foundation | Yes | | 3 | Analytics engine | Deterministic metrics, cohorts, trends, diagnostic drill-downs, traceability, projection refresh within 15 minutes, nightly reconciliation | Data foundation | Yes |
| 4 | Merchant API | Stable authenticated interfaces for dashboard data and analytics | Identity and access, analytics engine | Yes | | 4 | Merchant API | Stable authenticated interfaces for dashboard data and analytics | Identity and access, analytics engine | Yes |
| 5 | Merchant dashboard | Persian RTL dashboard, responsive navigation, accessible charts/tables and explanations | Merchant API | Yes | | 5 | Merchant dashboard | Persian RTL dashboard, responsive navigation, accessible charts/tables and explanations | Merchant API | Yes |
| 6 | AI assistance | AvalAI-backed explanation/recommendation workflow over sanitized aggregates | Analytics engine, merchant API | No | | 6 | AI assistance | AvalAI-backed explanation/recommendation workflow over sanitized aggregates | Analytics engine, merchant API | No |
@@ -48,6 +48,8 @@ Build sequence: data foundation → identity and analytics → API → dashboard
6. AI is post-MVP, receives only minimized/sanitized aggregates, and cannot become the source of record. 6. AI is post-MVP, receives only minimized/sanitized aggregates, and cannot become the source of record.
7. External calls have timeouts and bounded retries; jobs are idempotent and observable. 7. External calls have timeouts and bounded retries; jobs are idempotent and observable.
8. Production changes are reversible and backed by documented health checks and rollback steps. 8. Production changes are reversible and backed by documented health checks and rollback steps.
9. Only `Verified` is a confirmed successful session; `Paid` remains a separately reported state until an approved metric-catalogue revision says otherwise.
10. Iranian official holidays come from reviewed, versioned annual calendar snapshots; broader analytical event windows are explicitly labeled and versioned.
## Required capability specs ## Required capability specs