This repository is the operational control plane for the hackathon project. It will own Docker Compose, Nginx, environment templates, deployment automation, backup/restore scripts, and cross-repository release orchestration. Product code belongs in the backend and frontend repositories.

Current state: specifications, operations plan, adaptation contract, runbooks, and task list are approved. Phase 4 deployment implementation is authorized.

Repository topology

zarinpal-analytics-deployment/  # this repository
├── backend/                    # ignored checkout of zarinpal-analytics-backend
├── frontend/                   # ignored checkout of zarinpal-analytics-frontend
├── docs/
└── (deployment assets created through the authorized task list)

The intended production hostname is zarinpal.amiirkhl.ir. The deployment shape will follow the proven Qlockify structure while being reviewed and hardened for this service; it is not a byte-for-byte copy.

Documentation workflow

CAPABILITY-MAP.md is the approved Phase 0 decomposition.
Each capability receives a spec before implementation.
Surprising or hard-to-reverse decisions receive an ADR in docs/decisions/.
Raw datasets and database state are never committed.
Every material change is a small Conventional Commit.

Platform operations documents

docs/PLATFORM-OPERATIONS-SPEC.md defines the approved manual Qlockify-style production topology, lifecycle, observability phases, security, backup/restore, acceptance, and operator boundaries.
docs/QLOCKIFY-ADAPTATION-CONTRACT.md maps Qlockify's tracked deployment files and environment layout to the planned ZarinPal artifacts without requiring real server values during planning.
docs/runbooks/FIRST-SERVER-BOOTSTRAP.md defines the safe first-host sequence without implementing a bootstrap script.
docs/runbooks/BACKUP-RESTORE.md defines logical PostgreSQL backup, encryption/retention, guarded restore, and rehearsal.
tasks/plan.md and tasks/todo.md hold the approved implementation plan and dependency-ordered Phase 4 tasks.