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 ten remaining decisions have named answers/evidence.

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.