# Pelagia Portal — Design Document ## 1. Overview Pelagia Portal is an internal purchase order (PO) management web application for a maritime / vessel-operations company. It digitises the entire PO lifecycle — from a crew member raising a requisition, through manager approval and vendor validation, to accounts payment processing and final receipt confirmation — replacing ad-hoc email chains and spreadsheets with a single, auditable system. --- ## 2. Goals & Non-Goals ### Goals - Provide role-specific dashboards and workflows so every actor only sees what is relevant to their job. - Enforce a structured, auditable approval chain for every purchase order. - Notify all stakeholders at each state transition via email without manual action. - Give management real-time spend visibility by vessel, project, and time period. - Surface vendor information deficiencies before payment is blocked. ### Non-Goals - Direct integration with external accounting or ERP software (out of scope for v1). - Mobile-native apps (the web app is expected to be accessed on desktop/tablet). - Supplier-facing self-service portal. - Automated payment processing (Accounts team confirms payment manually). --- ## 3. Actors & Roles | Role | Description | Key Permissions | |---|---|---| | **Technical** | Deck / engine crew raising POs for technical vessel needs | Create, edit draft, submit, confirm receipt | | **Manning** | Crew-management staff raising POs for manning / crew needs | Same as Technical | | **Manager** | Approves or rejects POs; can request edits, add vendor IDs, or directly amend line items during review | Review, approve, reject, request edits, edit line items (versioned), view all POs, history reports | | **Accounts** | Processes payment for approved POs | View payment queue, mark as paid, view all POs | | **SuperUser** | Elevated user with cross-team operational authority | All Technical + Manning + Manager permissions | | **Auditor** | Read-only audit access across all records | View all POs, download audit trail, export reports | | **Admin** | System administrator | Manage users, vessels, accounts, vendors; full CRUD on all entities | --- ## 4. PO Lifecycle & State Machine ``` DRAFT ──(submit)──► SUBMITTED ──(system auto-move)──► MGR_REVIEW │ ┌──────────────────────────────────────┤ │ │ │ (no vendor ID) (request edits) (reject) ▼ ▼ ▼ VENDOR_ID_PENDING EDITS_REQUESTED REJECTED │ │ (ID provided) (resubmit) └────────────────────┘ │ (approve / approve+note) ▼ MGR_APPROVED │ (accounts picks up) ▼ SENT_FOR_PAYMENT │ (payment confirmed) ▼ PAID_DELIVERED │ (submitter confirms receipt) ▼ CLOSED ``` ### Allowed State Transitions | From | To | Actor | Trigger | |---|---|---|---| | DRAFT | SUBMITTED | Technical / Manning / SuperUser | Submit button | | SUBMITTED | MGR_REVIEW | System | Auto on submit | | MGR_REVIEW | VENDOR_ID_PENDING | Manager | Missing vendor ID | | VENDOR_ID_PENDING | MGR_REVIEW | Submitter / Manager | Vendor ID supplied | | MGR_REVIEW | EDITS_REQUESTED | Manager | Request edits action | | EDITS_REQUESTED | SUBMITTED | Technical / Manning / SuperUser | Resubmit after edits | | MGR_REVIEW | REJECTED | Manager | Reject action | | MGR_REVIEW | MGR_APPROVED | Manager / SuperUser | Approve or Approve+Note | | MGR_APPROVED | SENT_FOR_PAYMENT | Accounts | Pick up payment | | SENT_FOR_PAYMENT | PAID_DELIVERED | Accounts | Confirm payment | | PAID_DELIVERED | CLOSED | Technical / Manning / SuperUser | Confirm receipt | --- ## 5. Email Notification Matrix | Event | Notified Parties | |---|---| | PO submitted | Manager(s), Submitter (confirmation) | | Vendor ID requested | Submitter | | Vendor ID supplied | Manager | | Edits requested | Submitter (includes manager note) | | PO resubmitted after edits | Manager | | PO approved | Submitter, Accounts (with PO attachment) | | PO approved with note | Submitter (with note), Accounts | | PO rejected | Submitter (with rejection reason) | | Payment sent | Submitter, Manager | | Receipt confirmed | Manager, Accounts | | PO closed | Submitter, Manager, Accounts | --- ## 6. Screen Inventory ### 6.1 Authentication - **Login** — Employee ID / email + password. Role badge hints displayed. No self-registration; accounts provisioned by Admin. ### 6.2 Dashboards (role-specific landing pages) - **Technical / Manning Dashboard** — My open POs count, pending approvals, completed orders, quick-access "New PO" CTA. Full list of all POs (open and historical) is accessible and each PO is openable from the dashboard. - **Manager Dashboard** — Approvals awaiting count, approved POs listing with per-PO expense breakdown (line items + totals), spend by vessel (bar chart), spend by month (bar chart), recent activity feed. - **Accounts Dashboard** — Payment queue total value, ready-for-payment item count, recently processed items. ### 6.3 PO Creation & Editing - **New PO Form** — Multi-section form: - Order Info: title, vessel, account, project code, date required - Line Items: add / remove rows (description, qty, unit, unit price, total) - Vendor: vendor name, vendor ID (optional at creation), contact - Documents: drag-and-drop upload, file list with remove - Approval Flow: read-only visual showing who will review - **Edit PO** — Same form, pre-populated; only available when PO is in DRAFT or EDITS_REQUESTED. ### 6.4 Manager Approval - **Approval Queue** — Paginated list with search (PO number, vessel, submitter) and filters (date range, vessel). Each row shows PO number, submitter, vessel, amount, days waiting. - **PO Detail / Decision View** — Full PO summary, line items, attached documents, vendor info with verification callout (NEW if no ID). 4-action bar: Reject | Request Edits | Approve | Approve + Note. ### 6.5 Accounts Payment Queue - **Payment Queue** — Approved POs ready for payment. Shows PO summary, total amount, bank / payment ref fields. "Mark as Paid" action. ### 6.6 Order Tracking (Submitter) - **My Orders** — Card list with live status indicator, progress step-bar, latest manager note, and "Confirm Receipt" CTA when in PAID_DELIVERED. ### 6.7 Receipt Confirmation - **Receipt Screen** — Upload receipt / invoice image, delivery confirmation checklist, optional notes. Submits to close the PO. ### 6.8 Manager History / Reports - **History** — Full PO audit list with date, submitter, vessel, status, amount. Export to CSV / PDF. Filter by date range, vessel, status. ### 6.9 Administration (Admin role) - **User Management** — CRUD for user accounts, role assignment. - **Vessel Management** — CRUD for vessels. - **Account Management** — CRUD for accounts / cost centres. - **Vendor Management** — CRUD for approved vendor registry. - **Product Catalogue** — CRUD for products: product code, name, description. Last known unit price and associated vendor are read-only in this view — they are auto-populated when a PO containing that product is marked as paid. --- ## 7. Design System ### 7.1 Colour Palette | Token | Hex | Usage | |---|---|---| | `primary` | `#2563EB` | Primary actions, active states, links | | `primary-dark` | `#1D4ED8` | Hover on primary | | `success` | `#16A34A` | Approved, paid, closed states | | `warning` | `#D97706` | Pending review, edits requested | | `danger` | `#DC2626` | Rejected, destructive actions | | `neutral-50` | `#F9FAFB` | Page background | | `neutral-100` | `#F3F4F6` | Card / panel background | | `neutral-700` | `#374151` | Body text | | `neutral-900` | `#111827` | Headings | ### 7.2 Typography | Element | Font | Weight | Size | |---|---|---|---| | Headings (H1–H3) | Inter | 600–700 | 24 / 20 / 16 px | | Body | Inter | 400 | 14 px | | Labels / captions | Inter | 500 | 12 px | | Data / mono values | JetBrains Mono | 400 | 13 px | ### 7.3 Component Conventions - Cards use `rounded-lg`, `shadow-sm`, 16 px padding. - Status badges use pill shape with colour-coded background matching state machine colours. - Tables use alternating row shading, sticky header on scroll. - Forms use floating labels; validation errors appear below the field in `danger` colour. - Action buttons: primary = blue fill, secondary = white with border, danger = red fill. --- ## 8. User Stories (Priority P0 = must-have, P1 = should-have, P2 = nice-to-have) ### Submitter (Technical / Manning) | ID | Story | Priority | |---|---|---| | S-01 | As a submitter, I can create a PO with line items and attach documents. | P0 | | S-02 | As a submitter, I can save a PO as draft before submitting. | P0 | | S-03 | As a submitter, I can submit a draft PO for manager approval. | P0 | | S-04 | As a submitter, I receive an email when my PO is approved or rejected. | P0 | | S-05 | As a submitter, I can view the current status and history of all my POs. | P0 | | S-06 | As a submitter, I can provide a vendor ID when requested by a manager. | P0 | | S-07 | As a submitter, I can edit and resubmit a PO when edits are requested. | P0 | | S-08 | As a submitter, I can confirm receipt and upload a receipt document to close a PO. | P0 | ### Manager | ID | Story | Priority | |---|---|---| | M-01 | As a manager, I see all POs awaiting my approval in a queue. | P0 | | M-02 | As a manager, I can approve, reject, or request edits on a PO. | P0 | | M-03 | As a manager, I can add a note when approving or rejecting. | P0 | | M-04 | As a manager, I can flag a PO for vendor ID verification. | P0 | | M-05 | As a manager, I can view spend analytics by vessel and month. | P1 | | M-06 | As a manager, I can export a full PO history report as CSV or PDF. | P1 | ### Accounts | ID | Story | Priority | |---|---|---| | A-01 | As an accounts user, I see all manager-approved POs ready for payment. | P0 | | A-02 | As an accounts user, I can mark a PO as paid with a reference number. | P0 | | A-03 | As an accounts user, I receive email when a new PO enters my payment queue. | P0 | ### Admin | ID | Story | Priority | |---|---|---| | AD-01 | As an admin, I can create, edit, and deactivate user accounts. | P0 | | AD-02 | As an admin, I can manage vessels, accounts, and vendors. | P0 | | AD-03 | As an admin, I can manage the product catalogue (codes, names, descriptions). Last known prices and vendors are automatically updated when a PO is paid. | P1 | --- ## 9. Accessibility & Internationalisation - WCAG 2.1 AA compliance target. - All interactive elements keyboard-navigable with visible focus ring. - Colour is never the sole conveyor of meaning (icons + labels accompany status colours). - English only for v1; i18n architecture (react-i18next) to be wired up but not populated. --- ## 10. Open Questions - Should managers be able to directly edit a PO (bypass submitter) in exceptional circumstances? - What is the approval chain for high-value POs — single manager or dual sign-off? - Should the vendor registry be editable by managers, or Admin-only? - Is SSO (e.g., Azure AD) required for login, or internal credential management is sufficient?