zarinpal-analytics-frontend/PRODUCT.md

Product

Platform

web

Users

ZarinPal merchants and the teams responsible for monitoring their payment gateways. A merchant may own multiple terminals and needs to understand both the selected terminal and the merchant-wide picture without reading raw analytical output.

Product Purpose

Turn imported payment-session data into a Persian-first dashboard that helps a merchant understand payment flow, diagnose failed or retried transactions, follow fees, and compare performance with a privacy-safe cohort. Success means a merchant can sign in, select a terminal and reporting window, understand the result in plain language, and open the evidence behind it.

Positioning

The product joins ZarinPal's familiar merchant-panel interaction model with session-grain payment analytics, attempt history, transparent formulas, and privacy-preserving peer context.

Operating Context

• Authenticated desktop and mobile web dashboard used repeatedly during merchant operations.
• PostgreSQL is the authority for the imported immutable dataset; the Go API owns authentication, tenant scope, and metrics.
• Reporting is filtered by daily, Iranian weekly, Jalali-monthly, and Persian-season windows.
• A merchant may switch among their own payment terminals. The active period and terminal remain in the URL so a view can be copied and revisited.

Capabilities and Constraints

• Separate routed pages cover the overview, transactions, payment performance, fees, peer comparison, and methodology.
• Transaction rows open a routed detail view with the ordered history of attempts.
• Tables provide status, date-window, and amount-range filters without free-text search.
• Important metrics expose formulas and safe denominators without revealing payer identifiers or peer rows.
• Human-readable insights summarize performance with encouraging, factual language. They never fabricate causes or reveal another merchant's data.
• The frontend is SvelteKit 2, Svelte 5, strict TypeScript, and Tailwind CSS v4; the backend remains Go and PostgreSQL.
• The feature is previewed on an isolated local instance and is not merged without explicit user confirmation.

Brand Commitments

• Product name and supplied ZarinPal wordmark remain recognizable.
• The supplied current ZarinPal panel screenshots are the binding interaction and density reference.
• ZarinPal blue is the principal action and active-navigation color; yellow is a small brand accent.
• Persian is the primary product language and the interface is RTL.

Evidence on Hand

• Supplied ZarinPal panel screenshots showing the top utility bar, expanded/collapsed right sidebar, terminal selector, chart, filtered tables, and transaction detail layout.
• Supplied logo sheet at ../(challenge)/zarinpal-logo.jpg.
• Imported local payment dataset with merchant, terminal, session, and attempt records.
• Existing approved analytics, identity, privacy, and data-quality specifications in the frontend and backend repositories.

Product Principles

1. Explain the result before exposing the raw detail.
2. Keep every number traceable to a formula, period, unit, and merchant-owned record.
3. Preserve the fast scan patterns merchants already recognize from ZarinPal.
4. Make terminal scope and time scope obvious and shareable.
5. Encourage improvement without shaming or overstating causality.

Accessibility & Inclusion

Target WCAG 2.2 AA. Navigation, filters, chart values, tooltips, terminal selection, tables, and transaction history must remain keyboard-operable and understandable without relying on color or pointer hover.