Table of Contents
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Crewing Module
Authoritative build spec: Crewing Implementation Spec carries the full reconciled instructions — codebase changes, the final roles/permission and navigation matrices, and the detailed screen spec. This page is the design overview, aligned with that spec.
The Crewing Module (a.k.a. Manning) extends Pelagia Portal (PPMS) from a purchasing system into a crew lifecycle system. It manages the people who run Pelagia's dredgers and sites — from the moment a vacancy opens, through recruitment and onboarding, to day-to-day site HR (attendance, leave, PPE, documents) and finally to the monthly wage report that feeds Accounts.
It reuses the platform primitives already proven by the PO module: a single state machine per lifecycle, a centralised permission map, an audit trail of actions, file storage for documents, and the notifier for email/in-app events.
Why software
Today crewing lives in notebooks, WhatsApp, and spreadsheets (the source notes for this design were literally two notebook pages). The pain points it removes:
- Vacancies are reactive and untracked. A sign-off or a leave clash creates a gap that nobody formally owns until a vessel is short-handed. → Auto-raised Requisitions on sign-off / end-of-contract and on a leave clash.
- Candidate vetting is ad-hoc. Competency, document, reference and salary checks happen over chat with no record of who cleared what. → A gated Candidate Pipeline with an event log.
- Site data and office verification are disconnected. PMs hold PPE/leave/doc data on paper; the office can't see or verify it. → Site-entered records with an explicit MPO / Accounts verification step.
- Wage calculation is manual. Days-attended × salary is re-derived by hand every month. → A generated Wage Report per site.
What it does (salient features)
| Area | Capability |
|---|---|
| Requisitions | Auto-raised (on sign-off / end-of-contract, or when a leave clash leaves a rank short) or manually-raised vacancy for a rank on a vessel/site; reason (leave / end-of-contract / termination / medical / other). |
| Candidate pipeline | A 7-stage gated board: shortlist (ex-hand preferred) → competency & references → document verification → salary agreement → proposal → interview → selection / rejection with remarks. Everyone is interviewed; for returning ex-hands the interview can be waived only with Manager approval. |
| CV intake | Self-apply on the Pelagia site or MPO upload; CV parsed for age, vessel type, rank and experience, with manual fallback. |
| Onboarding | One selection event starts salary, victualing, attendance, experience accrual, PF tracking and the PPE issue checklist. |
| Crew records | Bank details, EPF/UAN, next of kin, emergency contact, contract letter, and role-based seafarer documents (STCW, Aadhaar, PAN, Passport, CDC, COC, photo, licence, medical fitness). |
| PPE issue register | Boiler-suit & shoe sizes plus issue tracking for the full PPE kit. |
| Leave & attendance | Site-level leave planner — the Site in-charge applies leave on behalf of crew, and an overlapping leave clash auto-raises a requisition. Daily attendance is captured on site and reviewed by the Manager (the MPO has no attendance access). |
| Appraisal | PM raises → MPO verifies → Manager approves. |
| Sign-off | Updates experience, closes the assignment, and auto-raises the backfill requisition. |
| Wage report | Monthly, per site: crew × salary × days attended (+ victualing), generated and sent to Accounts. |
| Verification | Office sign-off: MPO verifies everything except attendance (which the MPO cannot see — it is the Manager's to review); bank + EPF verified by Accounts. |
How it fits PPMS
- Same stack — Next.js 15 App Router, Prisma + PostgreSQL, NextAuth v5, Tailwind v4, shadcn/ui. See Crewing Architecture.
- Same patterns —
lib/requisition-state-machine.tsandlib/application-pipeline.tsmirrorlib/po-state-machine.ts; aCrewActionaudit row mirrorsPOAction; verification/permission gating reusesrequirePermission. - Shared entities —
Vessel(cost centre),Site,User,Notificationare reused; crew salary cost is attributable to the same cost-centre concept used by POs.
Page map
| Page | Purpose | Detail |
|---|---|---|
| Crewing Implementation Spec | Authoritative reconciled build instructions (design ⨝ docs) | Start here |
| Crewing Design Document | Goals, scope, domain narrative, decisions | — |
| Crewing Architecture | System & component diagrams, module layout | Component diagram |
| Crewing Data Model | Entities, enums, relationships | ER diagram |
| Crewing Workflows | Lifecycles & flows | Sequence + state diagrams |
| Crewing Use Cases | Actors × use cases | Use-case diagram |
| Crewing Roles and Permissions | Permission matrix extension | — |
| Crewing User Stories | Backlog by epic with acceptance criteria | — |
Status: design proposal. Entity, route and permission names are proposals to be confirmed in review (see Open Questions).
Pelagia Portal (PPMS)
Overview
Build & Run
System
Product
- Feature Catalogue
- Pages and Navigation
- Workflows
- Purchase Orders
- Vendors and GST Lookup
- Inventory and Catalogue
- Inventory on Approval
- Notifications
- File Storage
- Design System
Planned
Quality
Ops
Engineering
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.