pelagia-portal/.claude/agent-memory/devops-env-manager/project_services.md

name	description	metadata
project-services	All managed services, ports, startup commands, health checks, and env var notes for the Pelagia Portal dev environment	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