pelagia-portal/App/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Development
pnpm dev                    # Next.js + Turbopack at localhost:3000
pnpm lint                   # ESLint
pnpm type-check             # tsc --noEmit

# Tests
pnpm test                   # Unit tests (Vitest, jsdom)
pnpm test:watch             # Unit tests in watch mode
pnpm test:integration       # Integration tests (Vitest, node + real DB)
pnpm test:e2e               # E2E tests (Playwright, headless)
pnpm test:e2e:ui            # E2E tests with interactive UI
pnpm test:all               # All test suites

# Run a single test file
pnpm test -- tests/unit/po-line-items-editor.test.tsx
pnpm test:integration -- tests/integration/create-po.test.ts

# Database
pnpm db:migrate             # Create + apply migration (dev)
pnpm db:migrate:deploy      # Apply migrations (CI/prod)
pnpm db:seed                # Populate sample data
pnpm db:studio              # Prisma GUI at localhost:5555
pnpm db:reset               # Drop + recreate + seed (dev)

Architecture

Overview

Internal purchase order management system for a maritime company. Full-stack Next.js 15 App Router app with Prisma + PostgreSQL, NextAuth v5 credentials auth, and Tailwind CSS v4.

Key design decisions:

• Server Components for all data-fetching pages; Client Components only where interactivity is needed
• Server Actions for all mutations (form submissions, approvals, etc.)
• Prisma Decimal fields cannot be passed directly to Client Components — convert with Number() in the Server Component before passing as props (see po-detail.tsx → lineItemsForEditor pattern)
• File storage toggles automatically: Cloudflare R2 in production, .dev-uploads/ directory in development
• Email toggles automatically: Resend in production, console log in development

PO Lifecycle (State Machine)

lib/po-state-machine.ts enforces all status transitions. The canonical flow:

DRAFT → SUBMITTED → MGR_REVIEW → MGR_APPROVED → SENT_FOR_PAYMENT → PAID_DELIVERED → CLOSED
                        ↓↑
               EDITS_REQUESTED / REJECTED / VENDOR_ID_PENDING

Every status change is validated against the state machine and recorded as a POAction row (audit trail).

Role-Based Permissions

lib/permissions.ts defines hasPermission(role, permission) and requirePermission(role, permission). Roles: TECHNICAL, MANNING, ACCOUNTS, MANAGER, SUPERUSER, AUDITOR, ADMIN.

Pattern: Server Actions call requirePermission() at the top before any DB write.

Key Directories

• app/(portal)/ — All authenticated pages (portal layout with sidebar)
• app/api/po/[id]/export/ — PDF and XLSX export endpoint
• lib/validations/po.ts — Zod schemas for PO forms; exports TC_FIXED_LINE and TC_DEFAULTS
• lib/po-state-machine.ts — All valid status transitions with required roles
• lib/notifier.ts — Email dispatch (Resend in prod, console in dev)
• lib/storage.ts — File upload/download (R2 in prod, local in dev)
• components/po/ — PO-specific components (line items editor, status badge, etc.)
• tests/integration/helpers.ts — makeSession(), makePoForm(), fd() for integration test setup

Cost Centre Model

A PO's "cost centre" is either a Vessel or a Site. PurchaseOrder has both vesselId String? (nullable) and siteId String? — exactly one is set.

Form encoding: All PO creation/edit forms use a costCentreRef field with values v:<vesselId> (vessel) or s:<siteId> (site). Server actions parse this to set the correct FK.

Display pattern: po.vessel?.name ?? po.site?.name ?? "—" everywhere a cost centre name is shown.

URL pre-select: /po/new?costCentreRef=v:<id> or ?costCentreRef=s:<id>.

Terminology: Admin pages use the real entity names (Vessel Management, Sites). PO-facing pages use "Cost Centre" for the combined concept. Budget heads are labelled "Accounting Code" (not "Account").

GST Calculation

totalAmount = sum(quantity × unitPrice × (1 + gstRate)) for each line item. The gstRate is stored as a decimal on POLineItem (e.g., 0.18 = 18%). This applies in Server Actions when computing totalPrice per line and the PO totalAmount.

Environment Variables

NEXTAUTH_SECRET         # Required always
NEXTAUTH_URL            # Required always (e.g., http://localhost:3000)
DATABASE_URL            # PostgreSQL connection string

AZURE_AD_CLIENT_ID, AZURE_AD_CLIENT_SECRET, AZURE_AD_TENANT_ID
                        # Microsoft Entra SSO (prod). auth.ts reads them at module
                        # load — set placeholders in non-SSO/dev envs so it boots.

# Optional in dev (defaults to local storage + console email):
R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET_NAME, R2_PUBLIC_URL
RESEND_API_KEY, EMAIL_FROM, EMAIL_FROM_NAME

# Report Issue button (lib/forgejo.ts); token needs write:issue:
FORGEJO_URL, FORGEJO_REPO, FORGEJO_TOKEN

GST_SERVICE_URL         # GstService microservice (defaults to localhost:3003)
NEXT_PUBLIC_INVENTORY_ENABLED   # Inventory feature flag
NEXT_PUBLIC_ENV_LABEL   # When set, shows a non-prod banner (EnvBanner). Leave unset in prod.

Operations & automation

This repo runs a self-hosted issue-to-deploy pipeline on the pms1 server (Forgejo + headless Claude Code). See ../automation/README.md. Relevant when working in this codebase:

• The Report Issue button (portal header) files a Forgejo issue; a watcher triages it and, for auto-fixable ones, implements a fix and opens a PR. Deploys are gated on a human merging the PR and pushing a vX.Y.Z tag.
• Automated fixes and the staging instance run against pelagia_test, a daily mirror of the production database, in dev mode (console email, local storage). Migrations are applied to it, so its schema tracks master. Never assume an empty DB — it holds prod-like data.