zarinpal-analytics-deployment/CAPABILITY-MAP.md

# Capability Map

Status: **approved Phase 0 baseline**  
Implementation authorization: **not granted**

## Product intent

Build a production-shaped, Persian-first merchant analytics panel that turns payment-attempt data into accurate, traceable, numerical, and actionable insights. Each merchant can sign in with a dedicated username and password, see only its own detailed data, and compare itself with anonymized category/cohort aggregates.

The hackathon demo will seed one account per merchant. Where merchant profile fields are absent from the source dataset, clearly synthetic display data may be generated for presentation; synthetic values must never be represented as source facts.

## Capabilities and dependency order

| Order | Capability | Responsibility | Depends on | MVP |
|---:|---|---|---|:---:|
| 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, 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 |
| 7 | Platform operations | Compose, Nginx, CI/CD, observability, backup/restore, release and rollback | All deployables | Yes |

Build sequence: data foundation → identity and analytics → API → dashboard → platform operations → AI assistance.

## Repository boundaries

- `zarinpal-analytics-backend`: one Go repository containing the modular backend and independently runnable commands where needed (API, importer, migrations, jobs).
- `zarinpal-analytics-frontend`: SvelteKit 2, Svelte 5, strict TypeScript, Tailwind CSS v4.
- `zarinpal-analytics-deployment`: Compose/Nginx/scripts/configuration and orchestration only; service repositories appear as ignored nested checkouts during deployment.

## Dataset facts that constrain the design

- Source grain: one payment attempt, uniquely identified by `(session_key, try_seq)`.
- Observed volume: 2,213,289 attempts, 2,062,839 sessions, 343 merchants, 348 terminals, 5 categories.
- Observed period: 2026-01-01 through 2026-07-01.
- Nullability is material: response, PSP, issuer/card, verification timing, and settlement fields are incomplete.
- Source `adjusted_fee` is the merchant-fee field for this product and is normalized once per session as a real Rial amount; the challenge source name/value was confidentiality-adjusted.
- Raw CSV/database state is local operational input, not versioned source.

## Cross-cutting invariants

1. Tenant isolation is enforced server-side on every merchant-scoped operation.
2. Cross-merchant output is aggregate and anonymized; no row-level peer data is exposed.
3. Every displayed metric has a definition, source fields, filters, time window, and drill-down path.
4. Dataset imports are repeatable and produce a versioned manifest with checksum, counts, timestamps, and validation results.
5. Secrets stay outside Git; examples contain names and safe placeholders only.
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.
8. Production changes are reversible and backed by documented health checks and rollback steps.
9. `Paid` and `Verified` are both successful bank payments; `Paid` still requires merchant verification and `Verified` is finalized. Paid-volume and recovery metrics include both while verification metrics keep them separate.
10. Merchant fees are real Rial amounts stored/summed once per session; repeated attempt rows never multiply a fee.
11. 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.
12. 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.
13. 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.
14. Each section attempt is limited to 60 seconds and at most two transient retries with exponential backoff/jitter; deterministic errors fail immediately.
15. The worker pins pre-1.0 Asynq `v0.26.0`, runs at 16 jobs globally and 4/merchant by default, and changes require reviewed dependency/load evidence.
16. Start, manual-retry, and SSE limits use independent authenticated-user/merchant buckets and return `429` with `Retry-After` before work is queued. SSE heartbeats run every 15 seconds and authorized run-event replay lasts one hour.

## Required capability specs

Each capability spec must define objective, scope/non-scope, actors, functional requirements, data/API contracts, security and privacy requirements, failure behavior, observability, tests, acceptance criteria, migration/rollback considerations, and unresolved decisions. A capability may enter implementation only after its spec status is marked **Approved**.