zarinpal-analytics-deployment/docs/CROSS-REPOSITORY-PLAN-REVIEW.md

Cross-Repository Specification and Plan Review

• Status: Approved — cross-repository implementation authorized 2026-08-20
• Date: 2026-08-20
• Scope: zarinpal-analytics-backend, zarinpal-analytics-frontend, and zarinpal-analytics-deployment

Outcome

The approved product, data, analytics, identity, API, UX, and operations specifications are sufficiently resolved for implementation. The user approved all three repository plans/task lists and authorized Phase 4 implementation on 2026-08-20.

Confirmed shared contracts

Concern	Agreed contract	Owning repository
Dataset	One pinned archive is imported once into normalized PostgreSQL tables; raw challenge data is ignored by Git	Backend
Data lifetime	MVP payment facts are immutable after the sole completed import; future replacement or live writes require a new specification	Backend
Import activation	On the first server release only: start data services, migrate, import and reconcile, then activate public services	Deployment
Tenant authority	Merchant context comes only from the revocable server-side demo session, never from client-supplied merchant identifiers	Backend
Analytics	Day, Saturday–Friday week, Jalali month, and Persian season metrics follow catalogue 0.4.0	Backend
Async delivery	Four independently completing sections use Redis/Asynq and authenticated SSE; Asynq is pinned pre-1.0 at v0.26.0	Backend
Cache identity	Redis keys include merchant, sole completed dataset snapshot, metric version, period, and section; PostgreSQL has no MVP invalidation triggers	Backend
Payment states	Paid means bank payment succeeded but merchant verification did not; Verified completed both steps; money success includes both where specified	Backend
Detail/export	Authorized details reconcile to aggregates; selected detail views support bounded Persian CSV export with the shared projection	Backend / Frontend
API	REST/SSE contract is approved as OpenAPI 1.0.0; frontend transport types will be generated from the pinned artifact	Backend / Frontend
UI	SvelteKit 2, Svelte 5, TypeScript, Tailwind, RTL Persian digits, IRANYekanX Pro, responsive light/dark ZarinPal-inspired system	Frontend
Deployment	Three repositories, Docker Compose, Nginx, TLS, environment files, guarded operations, encrypted PostgreSQL backup/restore	Deployment

Implementation plan map

1. Backend foundation: Go workspace, normalized Ent/Atlas schema, guarded one-time importer, validation/promotion/recovery, and deterministic demo accounts.
2. Backend services: bounded demo authentication, metric query kernel, Redis/Asynq orchestration, details, exports, and provider integration.
3. Backend HTTP surface: OpenAPI conformance, middleware, auth/period/run/SSE/retry/detail/CSV endpoints, audit, and hardening.
4. Frontend: foundation and tokens, generated transport, shell/auth, dashboard sections, partial SSE states, detail/export workflows, responsive/accessibility/theme verification.
5. Deployment: adapt Qlockify's Compose/Nginx/environment/manual-release/backup operations, integrate first-start ordering, verify locally with safe placeholders, then perform the separately authorized server release with real runtime values.

Backend provider work and frontend visual-system work can proceed in parallel after separate implementation authorization. Deployment scaffolding can also proceed in parallel once command/build contracts are stable; production bootstrap and cutover remain sequential gates.

Deferred interface details (not planning blockers)

These are build-time choices, not unresolved product requirements:

• exact pinned OpenAPI generation/validation tools and repository command wrappers;
• exact frontend/backend build and health commands after their scaffolds exist (frontend history fallback is already restricted to non-API routes);
• exact backend/frontend command and environment-variable names after their scaffolds exist;
• the hosting path for human-readable API problem pages.

Server IP/DNS state, Git credentials, ACME email, ParsPack values, operator identity, and alert destinations are runtime inputs supplied when their operations are performed. They do not block implementation planning or local placeholder-based validation. Deployment uses no CI/CD pipeline, runner, or registry.

No secrets, raw dataset, generated database, credentials, certificates, backups, or runtime volumes may be committed.

Authorization gate

The user approved these plans and explicitly authorized implementation on 2026-08-20. Implementation must follow each repository's dependency-ordered task list and review checkpoints. Remote pushes remain forbidden until the user separately requests a push.