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.
- 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.
- 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.

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 |
| 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 |
| 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 |
@@ -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.
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.
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.
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.
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. 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