# 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?
