shad0w/pelagia-portal
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
pelagia-portal/Docs/01-design-document.md

12 KiB
Raw Permalink Blame History

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?