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.

AI growth analyst

The AI growth analyst is controlled by service-owned environment files; no AvalAI credential belongs in this deployment repository or in the frontend.

For local deterministic verification, set AI_GROWTH_ENABLED=true in the ignored backend .env and PUBLIC_AI_GROWTH_ENABLED=true in the ignored frontend .env. With AVALAI_API_KEY empty, the worker must not make a provider request: it persists and serves a deterministic PARTIAL report instead.

The backend .env.example is authoritative for the complete contract. The production operator must explicitly provide AVALAI_API_KEY, AVALAI_MODEL, AI_DAILY_REQUEST_BUDGET, and AI_DAILY_TOKEN_BUDGET before enabling the feature. AVALAI_BASE_URL, AI_MAX_CONCURRENT, AI_CREATE_PER_MINUTE, and AI_UNCACHED_SCOPES_PER_DAY remain configurable safety limits. Never place AVALAI_API_KEY in a public frontend variable.