diff --git a/AGENTS.md b/AGENTS.md index 5e752f4..1627157 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,9 @@ 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. -- Analytics are calculated lazily by the API and persisted as typed PostgreSQL projections. Database-managed merchant/cohort revisions invalidate affected projections on insert; no scheduled analytics worker or Redis service is deployed for the MVP. +- 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. +- 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. - Health checks distinguish liveness from readiness. - Backups are encrypted where supported, validated, retention-aware, and paired with rehearsed restores. diff --git a/CAPABILITY-MAP.md b/CAPABILITY-MAP.md index 31bb155..575ecd3 100644 --- a/CAPABILITY-MAP.md +++ b/CAPABILITY-MAP.md @@ -15,8 +15,8 @@ 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, traceability, lazy PostgreSQL-backed merchant/cohort projections with insert-triggered revision invalidation | Data foundation | Yes | -| 4 | Merchant API | Stable authenticated interfaces for dashboard data and analytics | Identity and access, analytics engine | 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 | +| 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 | | 7 | Platform operations | Compose, Nginx, CI/CD, observability, backup/restore, release and rollback | All deployables | Yes | @@ -50,7 +50,8 @@ 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. Analytics are calculated on first relevant access and cached by merchant/cohort source revision and metric-definition version; the MVP deploys no scheduled analytics worker or Redis. +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. ## Required capability specs