AGENTS.md

Runtime And Workspace

Use Node 22+ and pnpm 11; packageManager pins pnpm@11.5.2.
This is a pnpm workspace: apps/api is NestJS/Prisma, apps/player is Vue H5 on :5173, apps/admin is the unified platform-admin + agent Vue app on :5174, and packages/shared holds shared types/constants plus public assets.
The frontends alias @thebet365/shared to packages/shared/src/index.ts because the built shared package is CommonJS; update shared source exports, not only dist.
packages/shared build runs scripts/generate-phone-countries.mjs before tsc.

Start local infrastructure with docker compose up -d; this exposes PostgreSQL on 5432 and Redis on 6379.
Copy env for the API as cp .env.example apps/api/.env; Nest reads .env from the API working directory when run via the workspace filter.
First database setup from repo root: pnpm db:generate, then pnpm db:migrate, then pnpm db:seed.
pnpm dev:api runs scripts/ensure-port-free.mjs 3000 and will kill any listener on port 3000 before starting Nest watch.
If starting apps separately, start API before pnpm dev:player or pnpm dev:admin; both Vite servers proxy /api to http://localhost:3000.

pnpm dev builds shared once, then runs all workspace dev scripts in parallel.
pnpm dev:admin and pnpm dev:manage are the same admin app.
Full verification is pnpm build and pnpm test; there is no root lint or formatter script in current manifests.
API tests: pnpm --filter @thebet365/api test.
Focused API Jest test: pnpm --filter @thebet365/api exec jest settlement-calculator.spec.ts --runInBand; avoid pnpm ... test -- ... for focused args because pnpm passes the literal -- through to Jest here.
Frontend typecheck/build: pnpm --filter @thebet365/player build and pnpm --filter @thebet365/admin build.
Admin bundle report: pnpm --filter @thebet365/admin build:analyze.

API URLs use the global /api prefix; Swagger is at /api/docs in non-production or when ENABLE_SWAGGER is truthy.
AppModule installs a global JwtAuthGuard; public endpoints must use @Public() from apps/api/src/shared/common/decorators.ts.
Keep business rules in apps/api/src/domains/*; apps/api/src/applications/{player,admin,agent} should stay as portal/controller orchestration.
Wallet changes should go through ledger/wallet services; UAT docs explicitly forbid direct balance edits for settlement fixes.
After editing apps/api/prisma/schema.prisma, run pnpm db:generate; use pnpm db:migrate for dev migrations and pnpm db:migrate:deploy for deployment.

Edit .ts and .vue sources in apps/player/src and apps/admin/src; many .js siblings exist under src, but both index.html files load /src/main.ts and Vite resolution prefers TS before JS.
Admin is one app for both ADMIN and AGENT accounts; route/menu gating is in apps/admin/src/router/index.ts and apps/admin/src/stores/auth.ts.
Player is mobile-first; performance expectations and required mobile paths are in docs/player-mobile-performance.md.

Jest specs live under apps/api/src/**/*.spec.ts with rootDir: src; the documented unit/regression suite is rule-oriented and does not require a live DB.
DB-backed smoke tests are exposed in the admin UI under smoke-tests; SmokeTestService allows them outside production, or in production only with ALLOW_SMOKE_TESTS=true.
UAT regression flow is documented in docs/UAT_CHECKLIST.md; it includes admin UI smoke tests plus manual wallet/agent-credit checks.

Production compose uses .env.docker: docker compose -f docker-compose.prod.yml --env-file .env.docker up -d --build or pnpm docker:up after creating .env.docker.
In production, keep SEED_DATABASE=false after first seed; production seed creates only admin plus WC2026 sample data, while dev seed includes agent/player demo accounts.
scripts/prod-init-db.sh is destructive by design: it requires CONFIRM=YES, backs up unless --skip-backup, truncates business data, then seeds production data.
Deployment packaging is pnpm pack:deploy; pack.mjs removes legacy shared public directories except flags and players before creating release/thebet365-deploy-*.zip.