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

docs: define analytics worker limits

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-08-20 16:34:30 +03:30
parent 5ea9687891
commit eba06f3dca
2 changed files with 6 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
AGENTS.md
View File

@@ -29,7 +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.
- First dashboard access enqueues bounded parallel analytics-section jobs. An on-demand backend worker calculates them, Redis caches/coordinates them with a configurable high TTL, and the API streams partial completion through authenticated SSE. This worker is event-driven, never scheduled. - An idempotent authenticated start request enqueues overview, payment-performance, fees, and peer-comparison jobs for bounded parallel calculation by a separate on-demand Go worker. Redis caches/coordinates each section for 30 days, and a separate authenticated SSE request streams partial completion. This worker is event-driven, never scheduled.
- Each section attempt has a 60-second timeout and at most two automatic retries for transient failures using exponential backoff with jitter. Deterministic failures are not retried.
- Redis and the analytics worker are private Compose services with health checks and resource limits; neither is exposed through Nginx. Redis is disposable cache/coordination state and is excluded from backup/restore. - Redis and the analytics worker are private Compose services with health checks and resource limits; neither is exposed through Nginx. Redis is disposable cache/coordination state and is excluded from backup/restore.
- Nginx disables response buffering/compression for the SSE route, preserves authenticated same-origin cookies and event ids, and uses reviewed stream timeouts/heartbeat behavior without weakening normal API proxy settings. - Nginx disables response buffering/compression for the SSE route, preserves authenticated same-origin cookies and event ids, and uses reviewed stream timeouts/heartbeat behavior without weakening normal API proxy settings.
- 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.

7
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, bounded parallel on-demand section jobs, high-TTL Redis cache, PostgreSQL revision invalidation | Data foundation | Yes | | 3 | Analytics engine | Deterministic metrics, cohorts, trends, diagnostic drill-downs, bounded parallel on-demand section jobs, 30-day Redis cache, PostgreSQL revision invalidation | Data foundation | Yes |
| 4 | Merchant API | Stable authenticated interfaces and tenant-scoped SSE for partial analytics delivery | Identity and access, analytics engine | Yes | | 4 | Merchant API | Stable authenticated interfaces and tenant-scoped SSE for partial analytics delivery | 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 |
@@ -50,8 +50,9 @@ Build sequence: data foundation → identity and analytics → API → dashboard
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. 9. Only `Verified` is a confirmed successful session; `Paid` remains a separately reported state until an approved metric-catalogue revision says otherwise.
10. MVP reporting periods are limited to daily, Saturday–Friday weekly, Jalali-month, and Persian-season views with consistent `Asia/Tehran` boundaries across database, API, and frontend. 10. MVP reporting periods are limited to daily, Saturday–Friday weekly, Jalali-month, and Persian-season views with consistent `Asia/Tehran` boundaries across database, API, and frontend.
11. First access enqueues all analytics sections for bounded parallel calculation; high-TTL Redis entries are keyed by merchant/cohort source revision, metric-definition version, and section. 11. An idempotent start request enqueues overview, payment-performance, fees, and peer-comparison sections for bounded parallel calculation by a separate Go worker; Redis caches each typed section for 30 days under merchant/cohort and metric-definition revisions.
12. Authenticated SSE exposes each section as it becomes ready. Redis and the on-demand worker remain private, and Redis is never a source of truth or backup target. 12. A separate authenticated SSE request exposes each section as it becomes ready. Redis and the on-demand worker remain private, and Redis is never a source of truth or backup target.
13. Each section attempt is limited to 60 seconds and at most two transient retries with exponential backoff/jitter; deterministic errors fail immediately.
## Required capability specs ## Required capability specs