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.
adjusted_fee is obfuscated and supports relative analysis only.
Raw CSV/database state is local operational input, not versioned source.

Cross-cutting invariants

Tenant isolation is enforced server-side on every merchant-scoped operation.
Cross-merchant output is aggregate and anonymized; no row-level peer data is exposed.
Every displayed metric has a definition, source fields, filters, time window, and drill-down path.
Dataset imports are repeatable and produce a versioned manifest with checksum, counts, timestamps, and validation results.
Secrets stay outside Git; examples contain names and safe placeholders only.
AI is post-MVP, receives only minimized/sanitized aggregates, and cannot become the source of record.
External calls have timeouts and bounded retries; jobs are idempotent and observable.
Production changes are reversible and backed by documented health checks and rollback steps.
Only Verified is a confirmed successful session; Paid remains a separately reported state until an approved metric-catalogue revision says otherwise.
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.
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.
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.
Each section attempt is limited to 60 seconds and at most two transient retries with exponential backoff/jitter; deterministic errors fail immediately.
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.
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.

5.4 KiB Raw Blame History Unescape Escape