Table of Contents
- Crewing Workflows
- 1. Requisition lifecycle
- 2. Candidate pipeline (Application)
- 3. Assignment lifecycle
- 4. Appraisal lifecycle
- 5. Wage report status
- 6. Sequence — sign-off → auto-requisition → fill
- 7. Sequence — candidate self-apply + CV parse
- 8. Sequence — recruitment pipeline (vetting → onboard)
- 9. Sequence — site data entry & office verification
- 10. Sequence — monthly wage report
- 11. Side-effects of onboarding (the one event that starts everything)
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 Workflows
Authoritative build spec: Crewing Implementation Spec carries the full reconciled instructions (codebase wiring, roles/nav matrices, screen spec). This page holds the detailed state/sequence diagrams, aligned with that spec.
Every crewing lifecycle is enforced by a single state-machine module (the
po-state-machine.ts pattern) and recorded as CrewAction audit rows. This
page is the authoritative behaviour spec: state diagrams, transition
tables, and sequence diagrams for the end-to-end flows.
1. Requisition lifecycle
The vacancy. Raised automatically on sign-off / end-of-contract or on a leave clash, or manually.
stateDiagram-v2
[*] --> OPEN : raise (auto on sign-off / leave clash / manual)
OPEN --> SHORTLISTING : add candidates
SHORTLISTING --> PROPOSING : a candidate clears vetting
PROPOSING --> INTERVIEWING : interview scheduled
INTERVIEWING --> SELECTED : candidate selected (or Manager-approved waiver)
INTERVIEWING --> SHORTLISTING : all rejected, re-source
SELECTED --> FILLED : onboarded (assignment created)
OPEN --> CANCELLED : vacancy withdrawn
SHORTLISTING --> CANCELLED
FILLED --> [*]
CANCELLED --> [*]
| From | Action | To | Roles | Side-effect |
|---|---|---|---|---|
| — | raise |
OPEN | system (sign-off or leave clash) / MANNING / MANAGER | email MPO |
| OPEN | start_shortlist |
SHORTLISTING | MANNING | — |
| SHORTLISTING | propose |
PROPOSING | MANNING | email Manager |
| PROPOSING | schedule_interview |
INTERVIEWING | MANNING | email candidate |
| INTERVIEWING | select |
SELECTED | MANAGER | email candidate |
| INTERVIEWING | reject_all |
SHORTLISTING | MANNING | — |
| SELECTED | onboard |
FILLED | MANNING, MANAGER | onboarding side-effects |
| OPEN/SHORTLISTING | cancel |
CANCELLED | MANNING, MANAGER | — |
Site staff do not raise requisitions — they request relief cover, which the office converts into a requisition. Selection is Manager-approved (the MPO records the interview result; the Manager approves the salary structure and the selection). For a returning ex-hand the interview may be waived only with Manager approval — there is no automatic waiver path.
2. Candidate pipeline (Application)
The per-candidate gated vetting from notebook page 2, as a 7-stage board.
Many applications run per requisition; one ends in ONBOARDED. Everyone is
interviewed; for a returning ex-hand the interview is waived only with Manager
approval (interviewWaived is set after approval). Any gate can end in
rejection with remarks.
stateDiagram-v2
[*] --> SHORTLISTED
SHORTLISTED --> COMPETENCY_AND_REFERENCES
COMPETENCY_AND_REFERENCES --> DOC_VERIFICATION : pass
DOC_VERIFICATION --> SALARY_AGREEMENT : pass
SALARY_AGREEMENT --> PROPOSED : agreed (Manager approves structure)
PROPOSED --> INTERVIEW : proposal accepted
INTERVIEW --> SELECTED : pass / Manager-approved waiver
SELECTED --> ONBOARDED : onboard (joining formalities, Manager-approved)
COMPETENCY_AND_REFERENCES --> REJECTED : fail (remarks)
DOC_VERIFICATION --> REJECTED : fail (remarks)
SALARY_AGREEMENT --> REJECTED : not agreed
INTERVIEW --> REJECTED : fail (remarks)
ONBOARDED --> [*]
REJECTED --> [*]
Each transition writes an APPLICATION_GATE row (gate, result, note,
decidedById) so the office can see exactly who cleared what and why a
candidate was rejected.
3. Assignment lifecycle
An onboarded tour of duty.
stateDiagram-v2
[*] --> ACTIVE : onboard
ACTIVE --> ON_LEAVE : leave approved
ON_LEAVE --> ACTIVE : return
ACTIVE --> SIGNED_OFF : sign-off
ON_LEAVE --> SIGNED_OFF : sign-off (EOC / medical / etc.)
SIGNED_OFF --> [*]
onboard starts salary + victualing + attendance + experience + PF + PPE.
sign-off closes the tour, appends an EXPERIENCE_RECORD, and auto-raises a
backfill Requisition for the same rank/vessel.
3.1 Leave & the clash backfill
Leave is applied by the Site in-charge on behalf of a crew member
(LeaveRequest(APPLIED)) and decided by the Manager (APPROVED / REJECTED)
— the MPO has no role in leave. An approval moves the assignment to ON_LEAVE
for the period. On approval the
state machine checks the rank's cover on that vessel/site over the leave window:
if the approved leaves would drop the rank below its required strength, it
auto-raises a backfill Requisition (reason LEAVE, autoRaised) — the same
mechanism as the sign-off backfill, surfaced on the planner where the clash is
highlighted. (Attendance, by contrast, is recorded on site and reviewed by the
Manager; the MPO has no attendance access.)
sequenceDiagram
actor SIC as Site in-charge
participant SYS as App / state machines
actor MGR as Manager
participant DB as PostgreSQL
participant N as Notifier
actor MPO
SIC->>SYS: apply leave for crew member (dates)
SYS->>DB: LeaveRequest (APPLIED)
MGR->>SYS: approve leave
SYS->>DB: LeaveRequest APPROVED; assignment ON_LEAVE
SYS->>SYS: check rank cover over the leave window
alt clash — rank below required strength
SYS->>DB: create Requisition (reason=LEAVE, autoRaised, OPEN)
SYS->>N: notify MPO "vacancy (leave clash): <rank> on <vessel>"
N-->>MPO: email + bell
else covered
Note over SYS: no requisition needed
end
4. Appraisal lifecycle
stateDiagram-v2
[*] --> DRAFT : PM starts
DRAFT --> SUBMITTED : PM submits
SUBMITTED --> MPO_VERIFIED : MPO verifies
SUBMITTED --> REJECTED : MPO returns (remarks)
MPO_VERIFIED --> MANAGER_APPROVED : Manager approves
MPO_VERIFIED --> REJECTED : Manager returns
MANAGER_APPROVED --> [*]
REJECTED --> DRAFT : revise
5. Wage report status
stateDiagram-v2
[*] --> DRAFT : month-end trigger
DRAFT --> GENERATED : lines computed
GENERATED --> MANAGER_APPROVED : Manager approves
MANAGER_APPROVED --> SENT_TO_ACCOUNTS : dispatched
SENT_TO_ACCOUNTS --> [*]
6. Sequence — sign-off → auto-requisition → fill
sequenceDiagram
actor SS as Site staff (PM)
participant SYS as App / state machines
actor MPO
actor MGR as Manager
participant DB as PostgreSQL
participant N as Notifier
SS->>SYS: sign off crew member (EOC)
SYS->>DB: assignment → SIGNED_OFF
SYS->>DB: append EXPERIENCE_RECORD
SYS->>DB: create Requisition (autoRaised, OPEN)
SYS->>N: notify MPO "vacancy: <rank> on <vessel>"
N-->>MPO: email + bell
MPO->>SYS: start shortlist, add candidates
SYS->>DB: applications (SHORTLISTED)
Note over MPO,SYS: candidate pipeline (see §7)
MPO->>SYS: select candidate → onboard
SYS->>SYS: onboarding side-effects
SYS->>DB: requisition → FILLED, assignment ACTIVE
7. Sequence — candidate self-apply + CV parse
sequenceDiagram
actor C as Candidate
participant WEB as /careers/apply (public)
participant API as /api/crewing/cv-parse
participant CVP as CvParseService
participant FS as File storage
participant DB as PostgreSQL
actor MPO
C->>WEB: fill form + upload CV
WEB->>FS: store CV (signed upload)
WEB->>API: parse CV
API->>CVP: extract age, vessel type, rank, experience
CVP-->>API: fields (best-effort)
alt extracted
API-->>WEB: pre-filled draft
else not extractable
API-->>WEB: empty draft (manual entry)
end
C->>WEB: confirm / correct details
WEB->>DB: CrewMember (PROSPECT) + Application(s)
WEB-->>MPO: appears in shortlist queue
Manual MPO upload follows the same path minus the public form: MPO uploads the CV and confirms the parsed fields.
8. Sequence — recruitment pipeline (vetting → onboard)
sequenceDiagram
actor MPO
participant SYS as application-pipeline
actor MGR as Manager
actor C as Candidate
participant DB as PostgreSQL
MPO->>SYS: competency & references check
SYS->>DB: gate(competency_reference)=VERIFIED
MPO->>SYS: document verification
SYS->>DB: gate(document)=VERIFIED
MPO->>SYS: salary agreement (propose structure)
SYS->>DB: gate(salary)=PROPOSED, proposedSalary
MPO->>C: proposal
alt interview held (everyone by default)
MPO->>SYS: schedule + record interview result
SYS->>DB: gate(interview)=VERIFIED
else returning ex-hand, waiver requested
MPO->>MGR: request interview waiver
MGR->>SYS: approve waiver
SYS->>DB: gate(interview)=WAIVED (Manager-approved)
end
MGR->>SYS: approve salary structure + select
SYS->>DB: application SELECTED
MGR->>SYS: onboard (joining formalities)
SYS->>DB: CrewAssignment ACTIVE, contract letter, employeeId
Note over SYS,DB: salary+victualing+attendance+experience+PF+PPE started
Any failed gate → gate=REJECTED + remarks → application REJECTED
(visible to the office with the reason).
9. Sequence — site data entry & office verification
sequenceDiagram
actor SS as Site staff
participant SYS as App
participant DB as PostgreSQL
actor MPO
actor ACC as Accounts
SS->>SYS: upload documents / PPE issue / next-of-kin / EPF
SYS->>DB: records (verificationStatus=PENDING)
par MPO verifies (all except attendance and leave)
MPO->>SYS: verify document / PPE / NoK
SYS->>DB: VERIFIED (verifiedById=MPO)
and Accounts verifies bank + EPF
ACC->>SYS: verify bank detail
ACC->>SYS: verify EPF (UAN/Aadhaar vs EPFO)
SYS->>DB: VERIFIED (verifiedById=Accounts)
end
SS->>SYS: record attendance (no verify gate)
SYS->>DB: attendance rows
Site staff see contract letters view-only except salary and bank details view-only; salary and full account numbers are gated. Attendance is entered on site and reviewed by the Manager only — the MPO has no attendance access; it has no verification gate.
10. Sequence — monthly wage report
sequenceDiagram
participant CRON as Month-end trigger
participant WR as wage-report.ts
participant DB as PostgreSQL
actor MGR as Manager
actor ACC as Accounts
participant EXP as /payroll/[id]/export
CRON->>WR: generate for site, period YYYY-MM
WR->>DB: read assignments + attendance + salary
WR->>DB: WageLine = days × dailyRate + victualing
WR->>DB: WageReport (GENERATED, totalAmount)
WR-->>MGR: notify "wage report ready"
MGR->>DB: approve → MANAGER_APPROVED
MGR->>DB: send → SENT_TO_ACCOUNTS
DB-->>ACC: appears in Accounts queue
ACC->>EXP: export XLSX/PDF for disbursement
11. Side-effects of onboarding (the one event that starts everything)
| Side-effect | What it creates / starts |
|---|---|
| Salary | activates the approved SalaryStructure |
| Victualing | begins per-day messing accrual |
| Attendance | opens daily attendance for the assignment |
| Experience | begins accrual on this vessel/rank (closed into EXPERIENCE_RECORD at sign-off) |
| PF | enables EPF tracking against the crew member's UAN |
| PPE | seeds the PPE issue checklist for the kit |
| Identity | assigns employeeId, sets CrewMember.status = EMPLOYEE |
| Requisition | flips the filled requisition to FILLED |
All recorded as a single ONBOARDED CrewAction with the created IDs in
metadata — the same "one transition, one audit row, declared side-effects"
discipline as PO approval.
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.