shad0w/pelagia-portal
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
pelagia-portal/.claude/agent-memory/devops-env-manager/project_services.md
Hardik 1c5727850a fix(gst): 0% GST rate no longer falls back to 18% 
parseFloat('0') is falsy in JS so `|| 0.18` silently discarded the user's
explicit 0% selection. Replaced with an explicit empty-string guard.
Adds e2e spec gst-rate.spec.ts covering all five GST rates (0/5/12/18/28%).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-27 00:00:51 +05:30

4.4 KiB
Raw Blame History

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
  • 14 migrations as of 2026-05-26 (latest: 20260521000000_remove_vessel_imo_number)

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