# Development

Use this as the practical setup and verification guide. `PROJECT_INSTRUCTIONS.md` remains the source of truth for constraints.

## Prerequisites
- Node.js 20.19+ or 22.12+ for the current Vite toolchain.
- npm.
- PostgreSQL client tools if running migration scripts (`psql` must be on `PATH`).
- Access to the external Postgres database through `DATABASE_URL` or backend DB variables.
- Docker is optional for local app containers.

## Install
Run installs separately because this repo does not define npm workspaces.

```bash
npm ci
npm --prefix backend ci
npm --prefix frontend ci
```

## Environment
- Copy `backend/.env.example` to `backend/.env` for backend runtime configuration.
- Copy `frontend/.env.example` to `frontend/.env` if the frontend needs non-default API or host settings.
- Do not commit real `.env` files.
- Root DB migration scripts read `DATABASE_URL` from the shell environment; they do not load `backend/.env` automatically.

Important variables:

| Variable | Used by | Notes |
| --- | --- | --- |
| `DATABASE_URL` | backend, root migration scripts | Preferred external Postgres connection string. |
| `DB_USER`, `DB_PASS`, `DB_HOST`, `DB_PORT`, `DB_NAME` | backend fallback | Used only when `DATABASE_URL` is absent. |
| `JWT_SECRET` | backend auth | Required for token/session-compatible auth paths. |
| `ALLOWED_ORIGINS` | backend CORS | Comma-separated allowed frontend origins. |
| `SESSION_COOKIE_NAME`, `SESSION_TTL_DAYS` | backend cookies | Optional; defaults are defined in code. |
| `VITE_API_URL` | frontend | Defaults to `http://localhost:5000`. |
| `VITE_ALLOWED_HOSTS` | Vite dev server | Comma-separated host allowlist. |
| `PLAYWRIGHT_BASE_URL` | Playwright | Defaults to `http://localhost:3010`; the e2e runner starts Vite on this URL. |

## Run Locally
Docker dev stack:

```bash
docker compose -f docker-compose.dev.yml up
```

Separate terminals:

```bash
npm run dev:backend
npm run dev:frontend
```

Default local endpoints:
- Backend: `http://localhost:5000`
- Frontend through Docker compose port mapping: `http://localhost:3010`
- Frontend direct Vite default: `http://localhost:5173`

## Verification Commands
Root entry points:

```bash
npm test
npm run lint
npm run typecheck
npm run audit
npm run build:backend
npm run build:frontend
npm run build
npm run test:e2e
```

`npm run test:e2e` uses `frontend/scripts/run-playwright.mjs` to start Vite, run
Playwright, and shut Vite down cleanly. Pass Playwright flags after `--`, for
example `npm run test:e2e -- --reporter=list --workers=1`.

Migration checks:

```bash
npm run db:migrate:status
npm run db:migrate:verify
npm run db:migrate:stale:check
```

Do not run `npm run db:migrate` against a shared or production database unless that is the explicit operator task.

## Common Troubleshooting
- `DATABASE_URL is required`: export/set `DATABASE_URL` in the shell before root migration commands.
- `psql executable was not found in PATH`: install PostgreSQL client tools.
- Frontend cannot reach backend: confirm `VITE_API_URL`, backend port `5000`, and backend `ALLOWED_ORIGINS`.
- Playwright starts the frontend but API calls fail: start the backend separately or use the Docker dev stack.
- CORS blocked origin: add the exact frontend origin to `ALLOWED_ORIGINS`.

## Before Finishing Work
- Re-read `AGENTS.md` and any relevant deeper doc.
- Run the smallest useful checks first.
- For API behavior changes, add/update Jest tests with negative cases.
- For user-facing UI behavior changes, add/update focused Playwright coverage.
- Summarize any command that failed, whether it appears pre-existing, and the unresolved risk.