Local Setup

Required software

Tool	Purpose
Node.js 20+ (Node 24 used in development)	Frontend toolchain (Vite 8, TypeScript 6)
npm	Frontend dependency management
Python 3.10+	Flask API
pip + venv	API dependencies
(Optional) Supabase project or demo project	Real database access
(Optional) Playwright browsers	Smoke/E2E suites

Repository layout

dps-code-api/        Flask API + migrations + contract tests
ecc-dps-dashboard/   React/Vite dashboard + Training Center
discord-oauth-proxy/ Cloudflare Worker (deploy-time only)

Frontend setup

cd ecc-dps-dashboard
npm install
npm run dev          # Vite dev server (default port 5173)

• The dev server proxies /api to DPS_API_BASE_URL when set in the environment (see vite.config.ts). Create a local .env.local with:

  # Public API URL the browser bundle talks to:
  VITE_DPS_API_BASE_URL=https://demo-api.eccdps.org
  # Optional: API key the dev proxy adds to /api requests (bot-path testing):
  # DPS_API_KEY=...

• The dashboard requires a valid browser session: open /login and complete Discord OAuth against the environment you pointed at.

• To exercise the Training Center locally, visit http://localhost:5173/training (the /training path boots the training app without needing the subdomain).

• The demo environment is the recommended local target (fictional data, full reset via the demo reset controls). See ecc-dps-dashboard/DEMO_ENVIRONMENT.md.

Backend setup

cd dps-code-api
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

The API requires configuration to boot:

• SUPABASE_URL + SUPABASE_KEY (service role) + OAUTH_SESSION_SECRET are required (production config; the app fails fast without them).
• ERLC_RELAY_URLS + ERLC_RELAY_TOKEN (or ERLC_SERVER_KEY for local dev) are required at import time (the erlc_relay module validates at import).
• The full variable list is in the Environment variables reference.

Run the API:

flask --app app run --debug          # or: python app.py

The root route (GET /) returns DPS API Online; the API resolves the environment from the request host. For local development, ECCDPS_DEV_HOSTS can map a local hostname to an environment (see environment.py), or you can point DASHBOARD_ORIGIN at your dev origin.

Local database considerations

• The API talks to a real Supabase project (production or demo). There is no bundled local database; db.url (or DB_URL) is only consumed by apply_rpc_migrations.py for applying migrations.
• Never point local tooling at the production project by default. Use the demo project for development. apply_rpc_migrations.py connects wherever its connection string points — verify the target before running it.
• Schema changes: write a migration file and apply it to a scratch/demo project (see Migrations); never edit already-applied migrations to change production behavior.

Testing considerations

• Backend contract suites are standalone scripts run with the API's Python environment (see Testing).
• Frontend build/typecheck: npm run build (tsc -b && vite build).
• Production smoke suites require saved OAuth storage state and a reachable production/demo API — they are not part of a clean-checkout local flow.

Common local issues

Symptom	Fix
npm run dev API calls fail	Set VITE_DPS_API_BASE_URL; check the API is reachable and CORS allows your origin
API won't boot	Missing production config or ER:LC config — set the required variables
401 on everything	No session; complete Discord OAuth at /login (and be an allowed agent in the target environment)
Login rejects you	Your Discord ID is not in agents (or not on the demo allowlist)
Training Center shows white screen	Use the /training path; ensure ToastProvider/AuthProvider mount (both apps mount them)

Related reading

• Testing
• Environments
• Troubleshooting