zarinpal-analytics-deployment/docs/LOCAL-DEVELOPMENT.md

Local development without Docker Compose

This Windows-only helper runs the API, analytics worker, and frontend directly from the three sibling repositories. PostgreSQL and Redis must already be reachable locally. It does not create databases, run migrations/imports, generate credentials, edit service-owned environment files, or start Docker.

Prerequisites

• Go and npm are on PATH.
• PostgreSQL is reachable at 127.0.0.1:5432.
• Redis is reachable at 127.0.0.1:6379.
• The backend has cmd/api and cmd/worker, plus a protected backend-owned .env.
• The frontend has a package.json dev script and its frontend-owned local environment file.
• Dependencies, migrations, the one-time importer, and demo merchant creation have already completed through their owning repositories.

The helper only reports variable names or file paths when validation fails. It never prints resolved environment values. Runtime process metadata and logs are written under ignored .local/.

Commands

Run these from the deployment repository in PowerShell:

.\scripts\local-dev.ps1 check
.\scripts\local-dev.ps1 start
.\scripts\local-dev.ps1 status
.\scripts\local-dev.ps1 stop

The default sibling locations are ../zarinpal-analytics-backend and ../zarinpal-analytics-frontend. Override them with -BackendPath and -FrontendPath when necessary.

stop terminates only the process trees whose PID and start time match the ignored state file. A stale or reused PID is not terminated.

Verification

pwsh -NoProfile -File .\tests\local-dev.tests.ps1
pwsh -NoProfile -File .\scripts\local-dev.ps1 check

After start, open the frontend URL declared by the frontend development server. Inspect .local/logs/*.err.log if a process exits during or after startup.