zarinpal-analytics-deployment/tasks/todo.md

# Platform Operations implementation tasks

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

## Task 0: Approve specification and resolve blocking decisions

**Description:** Review the platform spec/ADRs and record every host, runner, version, route, capacity, backup, TLS, and ownership decision before implementation.

**Acceptance criteria:**
- [ ] `PLATFORM-OPERATIONS-SPEC.md` status is explicitly approved by the stakeholder.
- [ ] ADR 0002 is accepted or replaced; ADR 0003 remains consistent with frontend commit `64f5ac2`.
- [ ] All remaining platform decisions have named answers/evidence; the frontend font ownership/delivery decision is already resolved by `64f5ac2` and ADR 0003.

**Verification:** Manual stakeholder approval and clean documentation diff.

**Dependencies:** None

**Files likely touched:** `docs/PLATFORM-OPERATIONS-SPEC.md`, `docs/decisions/0002-immutable-cross-repository-releases.md`

**Estimated scope:** Small (1–2 files)

## Task 1: Define release manifest and safe configuration schemas

**Description:** Create machine-validated schemas/examples for exact release provenance, compatibility metadata, active/previous pointers, safe public configuration, and external secret files.

**Acceptance criteria:**
- [ ] Synthetic valid/invalid manifests prove immutable three-repository/image constraints.
- [ ] Examples contain no secret-like values and name every required configuration input.
- [ ] Font provenance is only frontend SHA/image digest; no injection field/path exists.

**Verification:** Schema tests plus secret scan over staged files.

**Dependencies:** Task 0

**Files likely touched:** release/config schemas, safe examples, focused tests (maximum 5 files)

**Estimated scope:** Medium (3–5 files)

## Task 2: Implement data-service Compose foundation

**Description:** Add PostgreSQL/Redis pinned services, isolated data network, volumes, authentication, health checks, AOF policy, resources, and no host port publishing.

**Acceptance criteria:**
- [ ] Compose renders with pinned digests and healthy PostgreSQL/Redis.
- [ ] Redis loss is explicitly non-authoritative and its volume is excluded from backup.
- [ ] External/local port inspection finds no PostgreSQL/Redis host listener.

**Verification:** Compose validation, health inspection, network/port policy tests.

**Dependencies:** Task 1

**Files likely touched:** Compose files and focused topology tests (maximum 5 files)

**Estimated scope:** Medium (3–5 files)

## Task 3: Implement API, worker, and one-off lifecycle boundaries

**Description:** Wire immutable backend API/worker plus migration/import/admin one-offs with health gates, profiles, locks, graceful stop, and validated configuration.

**Acceptance criteria:**
- [ ] Normal startup waits for migration but never runs import/admin automatically.
- [ ] Worker is private/event-driven and retains pinned pre-1.0 Asynq `v0.26.0` contract.
- [ ] Failed migration blocks candidate API/worker; import path is exact/read-only/idempotent.

**Verification:** Lifecycle integration tests including failed migration and repeated import fixture.

**Dependencies:** Tasks 1–2 and approved backend command/health contract

**Files likely touched:** Compose lifecycle definitions, wrapper, focused tests (maximum 5 files)

**Estimated scope:** Medium (3–5 files)

## Task 4: Implement frontend and font artifact health

**Description:** Consume the ordinary frontend image/build context and verify static SPA plus tracked font output without copying/injecting assets in deployment.

**Acceptance criteria:**
- [ ] Candidate maps to frontend SHA/digest and serves expected font URL/MIME.
- [ ] Missing font/license input fails frontend CI or candidate smoke.
- [ ] Deployment files contain no font binary, license copy, private fetch, or font secret.

**Verification:** Image/static health test and repository policy scan.

**Dependencies:** Task 1 and approved frontend image contract at/after `64f5ac2`

**Files likely touched:** frontend service definition and focused smoke/policy tests (maximum 5 files)

**Estimated scope:** Small/Medium (2–4 files)

## Task 5: Implement Nginx canonical TLS and routing

**Description:** Add canonical host/default rejection, ACME/TLS, API/frontend separation, exact SSE proxy behavior, security headers, limits, and generic health routes.

**Acceptance criteria:**
- [ ] Only 80/443 are public; redirects/default-host behavior is exact.
- [ ] SSE buffering/cache/compression are off and heartbeat/replay survives reconnect.
- [ ] API never falls through to SPA; security/TLS/static-cache tests pass.

**Verification:** `nginx -t`, TLS/header/routing tests, streamed timing/reconnect test.

**Dependencies:** Tasks 3–4 and approved API/SSE paths/CSP

**Files likely touched:** Nginx template/entrypoint and focused tests (maximum 5 files)

**Estimated scope:** Medium (3–5 files)

## Checkpoint A: Runtime foundation

- [ ] Tasks 1–5 pass together from a clean Compose project.
- [ ] Only Nginx is public and all health/startup boundaries behave as specified.
- [ ] No secret, raw data, backup, TLS key, or duplicate font/license asset is tracked.

## Task 6: Implement release preflight, deploy, and rollback

**Description:** Build the serialized manifest-driven operator workflow for preflight, migration, service replacement, postflight, observation, active/previous switch, and rollback.

**Acceptance criteria:**
- [ ] Deploy uses image digests only and records evidence without secrets.
- [ ] Candidate health/migration/font failure preserves/restores prior release.
- [ ] Application-only rollback completes within 15 minutes and never auto-runs down migration.

**Verification:** Shell/unit tests plus induced staging failures and timed rollback drill.

**Dependencies:** Checkpoint A

**Files likely touched:** deploy/release scripts and focused tests (maximum 5 files per incremental slice)

**Estimated scope:** Split into multiple Medium tasks during implementation

## Task 7: Implement deployment-repository CI/CD

**Description:** Validate docs/config/Compose/Nginx/scripts/policies, accept authenticated candidates, enforce protected approval/locking, and invoke the manifest-driven release.

**Acceptance criteria:**
- [ ] PR workflows validate only and cannot access production secrets/deploy.
- [ ] Production release requires gates plus human approval and is serialized.
- [ ] Provenance/SBOM/scan/secret results attach to the release record.

**Verification:** Forge event tests with denied PR deploy, concurrent candidate events, failed gate, and approved release.

**Dependencies:** Task 6 and confirmed forge/runner/registry versions

**Files likely touched:** workflow plus CI-focused helpers/tests (maximum 5 files)

**Estimated scope:** Medium (3–5 files)

## Task 8: Coordinate backend/frontend candidate workflows

**Description:** In separately approved service-repository changes, publish one immutable tested image and send candidate metadata without direct production SSH.

**Acceptance criteria:**
- [ ] Backend gates include Go/migration/import/Asynq queue/recovery verification.
- [ ] Frontend gates include Svelte/accessibility/RTL/build/font verification.
- [ ] Service events cannot mutate production and use least-privilege credentials.

**Verification:** Each repository's CI on PR/main plus deployment candidate receipt test.

**Dependencies:** Task 7 and separate authorization in each service repository

**Files likely touched:** owned service workflow/tests only; not this deployment task

**Estimated scope:** Separate cross-repository tasks

## Task 9: Implement observability baseline

**Description:** Add bounded structured logging, private metrics/exporters/dashboards, release correlation, and symptom alerts/runbook links.

**Acceptance criteria:**
- [ ] All required RED/USE/worker/SSE/backup/TLS signals exist with bounded labels.
- [ ] Logs rotate and contain request/release correlation but no forbidden fields.
- [ ] Page/ticket alerts are test-fired and monitoring is not public.

**Verification:** Induced staging failure located from telemetry, cardinality/redaction checks, alert delivery test.

**Dependencies:** Checkpoint A and approved monitoring versions/budgets

**Files likely touched:** Compose monitoring slice/config/dashboards/tests, split to <=5 files per commit

**Estimated scope:** Split into multiple Medium tasks

## Task 10: Implement encrypted backup and retention

**Description:** Produce verified logical PostgreSQL backups, encrypt before durable storage, upload/verify remotely, retain three local/seven remote, and emit metrics.

**Acceptance criteria:**
- [ ] Archive/listing/checksums/manifest/remote verification gate success.
- [ ] Backup contains none of the explicit exclusions.
- [ ] Cleanup never removes the last known-good copy and uses exact validated paths.

**Verification:** Backup tests against fixture DB/object store, archive exclusion inspection, failed-upload/cleanup tests.

**Dependencies:** Tasks 1–3 and approved encryption/provider decisions

**Files likely touched:** backup script/config/tests/docs (maximum 5 files per slice)

**Estimated scope:** Medium (3–5 files)

## Task 11: Implement guarded restore and rehearsal

**Description:** Validate/decrypt/trust-check an explicit backup, require all production guards, restore into an empty destination, and run application validation.

**Acceptance criteria:**
- [ ] Each absent/mismatched production factor aborts before mutation.
- [ ] Partial/failed restore is never treated as usable or blindly retried.
- [ ] Clean rehearsal passes tenant/session/cold-cache/worker/SSE checks within two hours.

**Verification:** Destructive tests only against exact disposable fixtures, production-guard negative matrix, timed rehearsal.

**Dependencies:** Task 10 and approved switch strategy

**Files likely touched:** restore script/tests/docs (maximum 5 files per slice)

**Estimated scope:** Medium (3–5 files)

## Checkpoint B: Release and recovery

- [ ] Tasks 6–11 pass in staging with release/rollback/backup/restore evidence.
- [ ] Registry, runner, monitoring, object storage, and secrets remain least privilege/private.

## Task 12: Bootstrap and accept first production-shaped server

**Description:** Follow the reviewed bootstrap runbook, deploy an approved manifest, run the one-time data/demo setup, and capture every acceptance criterion.

**Acceptance criteria:**
- [ ] Access/firewall/Docker/DNS/TLS/deploy/monitoring boundaries pass.
- [ ] Migration/import/demo accounts/tenant isolation/analytics SSE pass.
- [ ] Encrypted remote backup and clean restore rehearsal meet RPO/RTO.

**Verification:** Completed runbook evidence and stakeholder acceptance review.

**Dependencies:** Checkpoint B and approved host/change window

**Files likely touched:** evidence/release records only; no secret/raw runtime artifacts

**Estimated scope:** Operational session

## Final checkpoint

- [ ] Every measurable acceptance criterion in the approved spec passes.
- [ ] Active and previous releases are exact and rollback-ready.
- [ ] Remaining decisions are resolved or explicitly defer launch.
- [ ] Documentation reflects implemented reality and no implementation gate was bypassed.