Pelagia Portal (PPMS)

Pelagia Portal — branded PPMS ("Pelagia Payment Management System") in the UI — is an internal purchase-order management system for a maritime / vessel-operations company. It digitises the full PO lifecycle — from a crew member raising a requisition, through manager approval and vendor validation, to accounts payment and receipt confirmation — replacing ad-hoc email chains and spreadsheets with a single, auditable workflow.

This wiki is the project's living reference. It is synthesised from the in-repo docs (Docs/, CHANGELOG.md, App/CLAUDE.md, App/README.md) and the current source (prisma/schema.prisma, lib/, app/, automation/). Where the original design specs and the shipped product diverge, the code and this wiki reflect the shipped product.

What it does

Role-specific dashboards & workflows so every actor sees only what's relevant to their job.
A structured, auditable approval chain for every PO, enforced by a single state machine.
Automatic email notifications at each state transition.
Spend visibility for management by cost centre (vessel) and time period.
Vendor validation — GSTIN lookup, geocoding for vendor-distance sourcing, and an auto-verify-on-payment flow.
Multi-company invoicing, structured PO numbers, a 3-level accounting-code hierarchy, Excel PO import, and (feature-flagged) site inventory.

The product at a glance


Stack	Next.js 15 (App Router) · TypeScript 5 · PostgreSQL 16 + Prisma 5 · NextAuth v5 · Tailwind v4 + shadcn/ui
Hosting	Self-hosted on a single Ubuntu server (`pms1`), Next.js under pm2, fronted by a Pangolin/Traefik tunnel
CI/CD	Forgejo + Forgejo Actions; an automated issue→fix→PR pipeline; a release tag (`vX.Y.Z`) deploys
Auth	Microsoft Entra SSO and credentials; 7 roles
Live at	`pms.pelagiamarine.com`

Start here

New to the codebase? → Getting Started
Understanding the system? → Architecture · Data Model · PO Lifecycle
Who can do what? → Roles and Permissions
What's been built? → Feature Catalogue · Pages and Navigation · Workflows
Designing UI? → Design System
What's coming? → Planned Features
Operating it? → Deployment and Operations · Issue-to-Deploy Pipeline
Unsure of a term? → Glossary

The full page list is in the sidebar. See Changelog for what shipped recently and Open Questions for decisions still pending sign-off.

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.