Getting Started

How to get the portal running locally for development. The app lives in App/ (package name pelagia-portal).

Prerequisites

Tool	Version
Node.js	≥ 20.11.0 LTS
pnpm	≥ 9.0.0
PostgreSQL	≥ 16 (local or Docker)

npm install -g pnpm     # if you don't have pnpm

Dev mode keeps it simple

In development the app needs only a database and an auth secret. Cloudflare R2 and Resend are not required — file uploads land in .dev-uploads/ and emails are printed to the terminal (lines prefixed 📧 [DEV EMAIL]). The switch is automatic, driven by NODE_ENV (next dev → development, next build/start → production). See File Storage and Notifications.

Setup

cd App
pnpm install

# 1. Environment
cp .env.example .env.local
#   minimum .env.local:
#   NEXTAUTH_SECRET=<openssl rand -base64 32>
#   NEXTAUTH_URL=http://localhost:3000
#   DATABASE_URL="postgresql://postgres:postgres@localhost:5432/pelagia_portal"

# 2. Database
pnpm db:migrate          # prisma migrate dev — create + apply migrations
pnpm db:seed             # vessels, accounts, vendors, products, demo users

# 3. Run
pnpm dev                 # Next.js + Turbopack at http://localhost:3000

auth.ts reads the Azure/Entra SSO variables at module load. In a non-SSO dev environment, set placeholder values for AZURE_AD_* so the app boots. See Environment Variables.

Seed credentials

pnpm db:seed creates demo users (password = role name + 1234):

Role	Email	Password
Technical	`tech@pelagia.local`	`tech1234`
Manning	`manning@pelagia.local`	`manning1234`
Accounts	`accounts@pelagia.local`	`accounts1234`
Manager	`manager@pelagia.local`	`manager1234`
SuperUser	`superuser@pelagia.local`	`super1234`
Auditor	`auditor@pelagia.local`	`audit1234`
Admin	`admin@pelagia.local`	`admin1234`

There is no self-registration — accounts are provisioned by an Admin or via SSO.

Common commands

# Development
pnpm dev                 # dev server (Turbopack)
pnpm lint                # ESLint
pnpm type-check          # tsc --noEmit

# Tests  (see the Testing page)
pnpm test                # unit (Vitest, jsdom)
pnpm test:integration    # integration (Vitest, node + real DB)
pnpm test:e2e            # E2E (Playwright)
pnpm test:all            # unit + integration

# Database
pnpm db:migrate          # create + apply migration (dev)
pnpm db:migrate:deploy   # apply migrations (CI/prod, non-interactive)
pnpm db:push             # push schema without a migration (prototyping)
pnpm db:seed             # demo data
pnpm db:seed:prod        # real reference data (users, companies, cost centres, sites, accounting codes — idempotent)
pnpm db:studio           # Prisma Studio at http://localhost:5555
pnpm db:reset            # drop + recreate + reseed (dev only)

# Misc
pnpm email:preview       # live-preview email templates at http://localhost:3001

GstService (GstService/) — a small Express + Playwright microservice that proxies the GST portal CAPTCHA/lookup. Optional in dev; defaults to http://localhost:3003. See Vendors and GST Lookup.

Project layout

App/
├── app/                 # Next.js App Router pages + API routes
│   ├── (auth)/login/
│   ├── (portal)/        # authenticated shell (sidebar + header)
│   └── api/             # auth, files, gst, notifications, po/export, reports
├── components/          # dashboard, inventory, layout, po, ui (shadcn/ui)
├── lib/                 # business logic (state machine, permissions, notifier, storage, …)
├── emails/              # React Email templates
├── prisma/              # schema, migrations, seed.ts, seed-prod.ts, accounting-codes-data.ts
└── tests/               # unit (Vitest), integration (Vitest+DB), e2e (Playwright)

See Architecture for the full layer breakdown and Data Model for the schema.

Pelagia Portal (PPMS)

Home

Overview

Build & Run

System

Product

Planned

Quality

Ops

Engineering

Tech Debt

Pelagia Portal (PPMS) — internal purchase-order management. Self-hosted on pms1, live at pms.pelagiamarine.com. This wiki tracks the shipped product; authoritative sources are the repo code, App/CLAUDE.md, Docs/, and CHANGELOG.md.