Crewing Use Cases

Authoritative build spec: Crewing Implementation Spec carries the full reconciled instructions (codebase changes, roles/nav matrices, screen spec). This page is the actor/use-case catalogue, aligned with that spec.

Actors and the use cases each can perform. The diagram uses a flowchart to approximate UML use-case notation (Mermaid has no native use-case diagram); actors are on the edges, use cases are rounded nodes, grouped by area.

1. Use-case diagram

flowchart LR
  SS([Site staff<br/>PM / APM / Site I-C])
  MPO([MPO])
  ACC([Accounts])
  MGR([Manager])
  CAND([Candidate])
  ADM([Admin])

  subgraph Requisition
    U1(["Raise requisition"])
    U1b(["Request relief cover"])
    U2(["Sign off crew → auto-requisition"])
    U2b(["Leave clash → auto-requisition (system)"])
    U3(["Cancel requisition"])
  end
  subgraph Recruitment
    U4(["Apply with CV"])
    U5(["Shortlist candidates"])
    U6(["Run vetting gates"])
    U7(["Reference check"])
    U8(["Propose & interview"])
    U9(["Select / reject with remarks"])
    U10(["Approve salary structure & list"])
    U11(["Onboard candidate"])
  end
  subgraph SiteHR["Site HR"]
    U12(["Apply for leave"])
    U12b(["Approve leave (Manager)"])
    U13(["View leave planner"])
    U14(["Record attendance"])
    U15(["Issue PPE (sizes)"])
    U16(["Upload documents / EPF / NoK"])
  end
  subgraph Verify["Office verification"]
    U17(["Verify docs / PPE / NoK"])
    U18(["Verify bank & EPF"])
  end
  subgraph Appraisal
    U19(["Raise appraisal"])
    U20(["Verify appraisal"])
    U21(["Approve appraisal"])
  end
  subgraph Payroll
    U22(["Generate wage report"])
    U23(["Approve wage report"])
    U24(["View / export wage report"])
  end
  subgraph Admin
    U25(["Manage ranks & doc requirements"])
  end

  SS --- U1b & U2 & U12 & U13 & U14 & U15 & U16 & U19
  CAND --- U4
  MPO --- U1 & U5 & U6 & U7 & U8 & U9 & U11 & U17 & U20 & U2b
  MGR --- U1 & U3 & U9 & U10 & U11 & U12b & U13 & U21 & U22 & U23 & U24
  ACC --- U18 & U24
  ADM --- U25

Site staff = PM / APM / Site In-charge only — the sole on-site logins. Every other on-vessel rank is a crew member / data subject with no account; site staff act on their behalf. Crew members are not actors here.

2. Use-case catalogue

ID	Use case	Primary actor	Pre-condition	Main success outcome
UC-01	Raise requisition	MPO / Manager	a rank is or will be vacant	`Requisition(OPEN)` created, MPO notified
UC-01b	Request relief cover	Site staff	a foreseen cover gap	`ReliefRequest(OPEN)`; office converts it into a requisition
UC-02	Auto-requisition on sign-off	System	crew member signed off	requisition raised automatically; experience updated
UC-03	Cancel requisition	Manager	requisition not yet filled	`CANCELLED` with reason
UC-04	Apply with CV	Candidate	careers form reachable	`CrewMember(PROSPECT)` + application; CV parsed or manual
UC-05	Shortlist candidates	MPO	requisition `OPEN`	applications `SHORTLISTED`; ex-hands preferred
UC-06	Run vetting gates	MPO	candidate shortlisted	competency/document/experience gates recorded
UC-07	Reference check	MPO	candidate in vetting	reference result recorded
UC-08	Propose & interview	MPO	gates cleared	proposal sent; interview result recorded — ex-hand interview waivable only with Manager approval
UC-09	Select / reject with remarks	MPO records, Manager approves	interview done or Manager-approved waiver	`SELECTED` (Manager-approved) or `REJECTED` + remarks
UC-10	Approve salary structure & candidate list	Manager	candidate proposed	salary structure approved
UC-11	Onboard candidate	MPO / Manager	candidate selected	`CrewAssignment(ACTIVE)`; salary/victualing/attendance/experience/PF/PPE started; employeeId issued; requisition `FILLED`
UC-12	Apply for leave (for a crew member)	Site in-charge	crew has active assignment	`LeaveRequest(APPLIED)` on the crew member's assignment
UC-12b	Approve / reject leave	Manager	leave applied	`APPROVED` → assignment `ON_LEAVE` (clash auto-raises a requisition); or `REJECTED`
UC-13	View leave planner	Site staff / Manager	—	timeline of contracts + leaves per site (the MPO has no leave access)
UC-14	Record attendance	Site staff	active assignment	daily `Attendance` rows (visible to site staff + Manager; not the MPO)
UC-15	Issue PPE	Site staff	active assignment	`PpeIssue` with size (boiler suit/shoes)
UC-16	Upload documents / EPF / next-of-kin / emergency	Site staff	crew exists	records created `PENDING` verification
UC-17	Verify docs / PPE / NoK	MPO	pending records exist	`VERIFIED` (everything except attendance and leave)
UC-18	Verify bank & EPF	Accounts	pending bank/EPF	`VERIFIED`; UAN/Aadhaar checked vs EPFO
UC-19	Raise appraisal	Site staff (PM)	active assignment	`Appraisal(SUBMITTED)`
UC-20	Verify appraisal	MPO	appraisal submitted	`MPO_VERIFIED`
UC-21	Approve appraisal	Manager	appraisal verified	`MANAGER_APPROVED`
UC-22	Generate wage report	Manager / system	month end	`WageReport(GENERATED)` per site
UC-23	Approve wage report	Manager	report generated	`MANAGER_APPROVED` → `SENT_TO_ACCOUNTS`
UC-24	View / export wage report	Accounts / Manager	report sent	XLSX/PDF export for disbursement
UC-25	Manage ranks & doc requirements	Admin	—	rank hierarchy + per-rank required documents
UC-26	Auto-requisition on leave clash	System	approved leaves overlap below a rank's required strength	`Requisition(OPEN, reason=LEAVE, autoRaised)`; MPO notified

3. Notable extensions / alternates

UC-04 alt — CV not parseable → manual field entry (never blocks intake).
UC-06/07/09 alt — any gate fails → REJECTED with remarks; application ends, requisition stays open for other candidates.
UC-08 alt — returning ex-hand → MPO requests an interview waiver; on Manager approval interviewWaived = true (never automatic).
UC-11 alt — joining formalities incomplete (no signed contract / unapproved salary) → onboarding blocked.
UC-16/17 alt — verifier rejects a record → back to PENDING with remarks for the site to correct.
UC-22 alt — attendance gaps flagged before generation; report can be regenerated until approved.
UC-12 note — crew are data subjects, not portal users, so the Site in-charge applies leave on their behalf (apply-only; the Manager decides it — the MPO has no leave role).
UC-14 note — attendance is recorded by site staff and reviewed by the Manager; the MPO has no attendance access (so the wage report, UC-22, is generated by the Manager / month-end job, not the MPO).
UC-26 — a leave clash (overlapping approved leaves below a rank's required strength) auto-raises a LEAVE requisition; same backfill path as UC-02.

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.