From 3608428c95fa64b09848aa7924326ccabc72fb87 Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Thu, 20 Aug 2026 12:36:28 +0330 Subject: [PATCH] docs: record approved capability map --- CAPABILITY-MAP.md | 55 ++++++++++++++++++++++ docs/decisions/0001-repository-topology.md | 20 ++++++++ 2 files changed, 75 insertions(+) create mode 100644 CAPABILITY-MAP.md create mode 100644 docs/decisions/0001-repository-topology.md diff --git a/CAPABILITY-MAP.md b/CAPABILITY-MAP.md new file mode 100644 index 0000000..d2ed1a3 --- /dev/null +++ b/CAPABILITY-MAP.md @@ -0,0 +1,55 @@ +# 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, ingestion, provenance, validation, quality reporting, synthetic merchant profiles | — | 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 | Data foundation | Yes | +| 4 | Merchant API | Stable authenticated interfaces for dashboard data and analytics | 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 + +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. + +## 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**. + diff --git a/docs/decisions/0001-repository-topology.md b/docs/decisions/0001-repository-topology.md new file mode 100644 index 0000000..a234c92 --- /dev/null +++ b/docs/decisions/0001-repository-topology.md @@ -0,0 +1,20 @@ +# ADR 0001: Three-repository topology + +- Status: Accepted +- Date: 2026-08-20 + +## Context + +The service needs independently testable/deployable frontend and backend code while retaining a single operational entry point patterned after Qlockify. Deployment-specific files must not pollute service repositories. + +## Decision + +Use three Git repositories: deployment, Go backend, and SvelteKit frontend. The deployment workspace clones the two service repositories into ignored `backend/` and `frontend/` directories and builds pinned revisions through the release workflow. + +## Consequences + +- Service changes can run focused CI and then trigger the deployment workflow. +- Deployment remains the authoritative location for Compose, Nginx, backup/restore, and server automation. +- A release manifest must record the exact commit SHA of each service; local nested checkouts alone are not sufficient provenance. +- Cross-repository contract changes require coordinated, backward-compatible rollout or an explicit release plan. +