---
name: project-services
description: All managed services, ports, startup commands, health checks, and env var notes for the Pelagia Portal dev environment
metadata:
  type: project
---

## Services

| Service | Port | Startup Command | Directory |
|---|---|---|---|
| pelagia-portal (Next.js) | 3000 | `node node_modules\next\dist\bin\next dev --turbopack` | `App/` |
| GstService (Express + Playwright) | 3003 | `npm run dev` (runs `tsx watch src/index.ts`) | `GstService/` |
| PostgreSQL 18 | 5432 | Windows service / already running | — |

## Directory Structure (verified 2026-05-26)

- Portal source: `App/` (contains package.json, next.config.ts, prisma/, app/, etc.)
- GstService source: `GstService/` (contains src/index.ts)
- `App/pelagia-portal/` — built artifact / deployed copy, NOT the source; has node_modules + .env.local but no package.json at root
- Project root (`C:\Users\shad0w\Documents\src\Peliagia_Portal`) has no package.json — the portal source is in `App/`

## Startup Order

1. Verify PostgreSQL is up on port 5432 (`pg_isready -U postgres`)
2. Install App/ deps if missing: `cd App && pnpm install --frozen-lockfile` (pnpm v10 — allowBuilds in pnpm-workspace.yaml handles build scripts cleanly)
3. Ensure `App/.env` exists with `DATABASE_URL` (Prisma reads `.env`, not `.env.local`)
4. Run `prisma migrate deploy` from `App/` using `.\node_modules\.bin\prisma.cmd migrate deploy`
5. Run `prisma generate` from `App/` using `.\node_modules\.bin\prisma.cmd generate`
6. Start GstService: `cd GstService && npm run dev > logfile 2>&1` (background)
7. Start pelagia-portal: `cd App && node node_modules\next\dist\bin\next dev --turbopack > logfile 2>&1` (background)
   - DO NOT use `pnpm dev` — pnpm 10 still runs pre-install hooks that may interfere; calling next directly is safer and consistent
8. Health check both services

## Health Checks

- pelagia-portal: `http://localhost:3000` — expect 200 or 307 (auth redirect to /login)
- GstService: `http://localhost:3003/health` — expect `{"ok":true,...}`
- PostgreSQL: `pg_isready -U postgres` — `:5432 - accepting connections`

## Environment

- Portal `.env.local` location: `App/.env.local` (copy from `App/pelagia-portal/.env.local` if App/ is a fresh checkout)
- Portal `.env` location: `App/.env` — must contain `DATABASE_URL` for Prisma CLI (Prisma only reads `.env`, not `.env.local`)
- Required dev vars: `NEXTAUTH_SECRET`, `NEXTAUTH_URL`, `DATABASE_URL`
- R2 and Resend vars not needed in dev (files go to `.dev-uploads/`, emails log to console)
- DATABASE_URL: `postgresql://postgres:postgres@localhost:5432/pelagia_portal`
- NEXTAUTH_URL: `http://localhost:3000`

## Node / Package Manager Setup

- Node.js: `C:\Program Files\nodejs` (must prepend to PATH)
- pnpm: v10.33.2, installed at `C:\Users\shad0w\AppData\Roaming\npm\node_modules\pnpm`
  - `$env:PATH` must include `$env:APPDATA\npm` to find pnpm
- PostgreSQL 18 bin: `C:\Program Files\PostgreSQL\18\bin`
- Set PATH at start of each session:
  `$env:PATH = "C:\Program Files\nodejs;C:\Program Files\PostgreSQL\18\bin;$env:APPDATA\npm;$env:PATH"`
- PGPASSWORD=postgres for psql/createdb commands

## Prisma Notes

- Use `.\node_modules\.bin\prisma.cmd` (not `node node_modules\.bin\prisma`) — the `.bin\prisma` shim is a bash script and fails on Windows/PowerShell
- Prisma reads `App/.env` for DATABASE_URL; `.env.local` is NOT read by Prisma CLI
- `prisma generate` EPERM on Windows = DLL locked by running Node process — normal
- 21 migrations as of 2026-05-31 (latest: `20260530000003_add_company`)
  - `20260530000000_vessel_optional_cost_centre` — makes PurchaseOrder.vesselId nullable
  - `20260530000001_account_hierarchy` — adds Account.parentId
  - `20260530000002_vessel_no_site_po_vessel_required` — drops Vessel.siteId, restores PO.vesselId NOT NULL
  - `20260530000003_add_company` — adds Company table + PurchaseOrder.companyId

## Log Files (when started as background processes)

- GstService: `C:\Users\shad0w\AppData\Local\Temp\gstservice.log`
- pelagia-portal: `C:\Users\shad0w\AppData\Local\Temp\portal.log`

## pnpm workspace

- `App/pnpm-workspace.yaml` uses `allowBuilds:` field (pnpm v10 syntax) to allow build scripts for @prisma/client, @prisma/engines, esbuild, prisma, sharp, unrs-resolver
- This resolves the ERR_PNPM_IGNORED_BUILDS issue from pnpm v11 era

## Notes

- pelagia-portal 307 response = auth redirect to /login — healthy, not an error
- GstService `browserConnected: false` at startup is normal — Playwright browser connects on first session
- Prisma migration scripts: `pnpm db:migrate` (dev), `pnpm db:migrate:deploy` (CI/prod) — run from App/
- `App/pelagia-portal/` is a deployed artifact directory (has .next/, node_modules, .env.local) — do not confuse with source