zarinpal-analytics-deployment/tasks/todo.md

Platform Operations implementation tasks

• Status: Ready for stakeholder review — implementation not authorized
• Canonical plan: tasks/plan.md

Task 0: Resolve implementation inputs and preserve the implementation gate

Description: Use the approved manual Qlockify-style specification to collect the concrete values and service contracts required for later implementation while preserving the separate explicit build-authorization gate.

Acceptance criteria:

• Revised Platform Operations spec is explicitly approved.
• ADRs 0001–0003 match the approved topology, manual release, and font decisions.
• Production connection values, protected secrets, repository URLs, service commands/routes, and responsible operators are recorded outside public Git where required.
• Stakeholder explicitly authorizes creation of deployment implementation artifacts.

Verification: Approved specification, clean documentation review, resolved slice inputs, and explicit build authorization.

Dependencies: None

Files likely touched: spec and ADRs only

Estimated scope: Small

Task 1: Define safe configuration and release records

Description: Define tracked placeholders, external protected secrets, deployment locking, and non-secret active/previous release records.

Acceptance criteria:

• Release record contains three SHAs, local image ids, migration, backup, operator, and health evidence.
• Configuration examples contain no real or plausible secret values.
• Font provenance uses frontend commit/build only; no second asset path exists.

Verification: Schema/format tests, secret scan, invalid-record tests.

Dependencies: Task 0

Files likely touched: examples/schema/tests/docs, maximum 5 files

Estimated scope: Medium

Task 2: Implement PostgreSQL and Redis Compose foundation

Description: Add pinned PostgreSQL 18 and Redis 7 Alpine, private data network, volumes, authentication, health, resources, and approved Redis AOF choice.

Acceptance criteria:

• Both services become healthy with explicit limits/tags.
• Neither publishes a host port.
• Redis is excluded from backup and loss does not affect PostgreSQL authority.

Verification: Compose validation, health, port/network, volume, Redis-loss tests.

Dependencies: Task 1

Files likely touched: Compose/config/tests, maximum 5 files

Estimated scope: Medium

Task 3: Implement backend, worker, and one-off boundaries

Description: Wire API/worker plus separate migration/import/admin commands and graceful lifecycle.

Acceptance criteria:

• Migration completes before API/worker readiness.
• Normal startup never runs import/admin; import uses one exact read-only path.
• first-start.sh starts data services, migrates, imports and reconciles the pinned archive, then starts public services only after success.
• Worker is private/event-driven and uses pinned pre-1.0 Asynq v0.26.0.

Verification: First-start, ordinary-startup, migration/import failure, checksum/count reconciliation, idempotent no-op, and shutdown integration tests.

Dependencies: Task 2 and approved backend commands

Files likely touched: Compose/service wrappers/tests, maximum 5 files per slice

Estimated scope: Medium

Task 4: Implement frontend build and font health

Description: Build the nested frontend checkout normally and verify static SPA/font output without deployment copies or injection.

Acceptance criteria:

• Build uses recorded frontend commit at/after 64f5ac2.
• Expected font resource returns 200 with correct content type.
• Deployment repository contains no font binary, FontLicense.txt, fetch, credential, or alternate path.

Verification: Build/static health plus repository-policy scan.

Dependencies: Task 1 and approved frontend build contract

Files likely touched: frontend deployment wrapper/service/tests, maximum 5 files

Estimated scope: Medium

Task 5: Implement Nginx and automatic TLS

Description: Adapt Qlockify's Nginx/Certbot pattern for canonical routing, Let's Encrypt, API/frontend separation, exact SSE behavior, security headers, and health.

Acceptance criteria:

• Only 80/443 are public; unknown hosts reject and canonical redirect is exact.
• Staging/production issuance and renewal/reload pass.
• SSE heartbeat/reconnect streams without buffering/cache/compression.

Verification: nginx -t, external TLS/header/routing checks, streamed SSE test.

Dependencies: Tasks 3–4 and approved routes/CSP

Files likely touched: Nginx/Certbot assets/tests, maximum 5 files per slice

Estimated scope: Medium

Checkpoint A: Runtime MVP foundation

• Tasks 1–5 pass from clean nested checkouts.
• Only Nginx is public; migration/import/admin/font/SSE boundaries behave correctly.
• No secret/raw data/runtime/font duplication enters deployment Git.

Task 6: Adapt Qlockify manual deploy and rollback

Description: Modify Qlockify's deploy flow for ZarinPal paths/services and three-hash release records while keeping interactive Git pulls as a separate operator prerequisite and removing unconditional destructive Git synchronization.

Acceptance criteria:

• Operator manually fast-forwards all three repositories to latest origin/main; the deployment command performs no pull and records all three hashes before build.
• Dirty/diverged checkout, build, migration, or health failure preserves the active release; a manual pull failure prevents deployment from starting.
• Previous hashes rebuild/restore within 15 minutes without automatic down migration.

Verification: Script tests plus induced staging failures and timed rollback drill.

Dependencies: Checkpoint A

Files likely touched: deploy script/release helper/tests/docs, maximum 5 files per slice

Estimated scope: Medium

Task 7: Adapt Qlockify encrypted backup/upload

Description: Reuse Qlockify's PostgreSQL dump, OpenSSL, rclone upload, and retention flow with ZarinPal paths/services/credentials and a non-secret manifest.

Acceptance criteria:

• Package contents, plain-SQL header/checksums, encryption, and remote verification gate success.
• Exactly three verified encrypted local and seven remote backups are retained.
• .env, secrets, Redis, TLS, CSV, credentials, logs, monitoring, font, and license are excluded.

Verification: Fixture database/object-store tests, exclusion inspection, failed-upload/cleanup tests.

Dependencies: Tasks 1–3 and approved backup inputs

Files likely touched: adapted backup/upload scripts/tests/docs, maximum 5 files per slice

Estimated scope: Medium

Task 8: Adapt Qlockify guarded restore

Description: Reuse Qlockify download/decrypt/restore flow while requiring explicit backup id, exact destination, empty target, and all production guards.

Acceptance criteria:

• Every absent/mismatched production factor aborts before mutation.
• No environment/secret/Redis restoration occurs.
• Clean restore passes schema/count/tenant/login/cold-cache/worker/SSE checks within two hours.

Verification: Disposable-database tests, guard negative matrix, timed rehearsal.

Dependencies: Task 7

Files likely touched: adapted restore scripts/tests/docs, maximum 5 files per slice

Estimated scope: Medium

Task 9: Bootstrap and accept MVP server

Description: Follow the reviewed bootstrap runbook, run the guarded first-start migration/import/application sequence, perform separate demo setup, and capture MVP evidence.

Acceptance criteria:

• Access/firewall/Docker/DNS/TLS/deployment boundaries pass.
• Three-hash release, migration, import, accounts, tenant isolation, worker/SSE, and font pass.
• MVP manual health/log/disk/certificate/queue checks and encrypted backup/restore pass.

Verification: Completed bootstrap/acceptance record.

Dependencies: Tasks 6–8 and approved server/window

Files likely touched: non-sensitive release/evidence records only

Estimated scope: Operational session

Checkpoint B: MVP ready

• Every MVP acceptance criterion passes.
• Active/previous three-hash releases and rollback are ready.
• Clean restore meets RPO/RTO.
• Stakeholder explicitly confirms the core project is ready, opening the observability phase.

Task 10: Add Prometheus and private exporters

Description: Add post-MVP collection for application, worker/SSE, PostgreSQL/Redis, host/container, backup/restore, and TLS signals.

Acceptance criteria:

• Required signals appear with bounded labels and retention.
• Prometheus/exporters are private and resource-limited.
• Merchant/user/request/card identifiers are absent from metric labels.

Verification: Target health, signal/cardinality/resource tests.

Dependencies: Checkpoint B

Files likely touched: split into <=5-file monitoring slices

Estimated scope: Multiple Medium slices

Task 11: Add Grafana dashboards and alerts

Description: Add private dashboards, release correlation, actionable symptom alerts, runbook links, and delivery testing.

Acceptance criteria:

• Service, worker/SSE, data, host, backup, and TLS dashboards answer the spec's operator questions.
• Only page/ticket alerts exist and each is actionable.
• Induced failures alert and can be diagnosed without source archaeology.

Verification: Dashboard review, induced failure, alert test-fire, redaction check.

Dependencies: Task 10

Files likely touched: split into <=5-file dashboard/alert slices

Estimated scope: Multiple Medium slices

Final observability checkpoint before AI

• Prometheus/Grafana phase meets its acceptance criteria.
• Alert delivery and runbook ownership are proven.
• Stakeholder explicitly approves beginning AI implementation.
• No CI/CD pipeline or automated deployment system was introduced.