zarinpal-analytics-deployment/tasks/todo.md

# Platform Operations implementation tasks

- Status: Not authorized — wait for explicit approval of the revised spec
- Canonical plan: `tasks/plan.md`

## Task 0: Approve revision and resolve implementation inputs

**Description:** Approve the confirmed manual Qlockify-style intent and resolve every remaining server/runtime/backup/phase-gate decision.

**Acceptance criteria:**
- [ ] Revised Platform Operations spec is explicitly approved.
- [ ] ADRs 0001–0003 match the approved topology, manual release, and font decisions.
- [ ] Every remaining decision has a named answer/evidence.

**Verification:** Stakeholder approval plus clean documentation review.

**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.
- [ ] Worker is private/event-driven and uses pinned pre-1.0 Asynq `v0.26.0`.

**Verification:** Startup/failure/import-idempotency/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 removing unconditional destructive Git synchronization.

**Acceptance criteria:**
- [ ] Latest `origin/main` is fast-forwarded and three hashes recorded before build.
- [ ] Dirty/diverged checkout, pull, build, migration, or health failure preserves the active release.
- [ ] 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:**
- [ ] Archive/listing/checksums/encryption/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, deploy manually, run one-time data/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.