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

24 KiB
Raw Blame History

Pelagia Portal — Design Document

Internal purchase-order management system for a maritime company.
This document describes every feature, page, workflow, and user story to guide UI/UX design.

1. Purpose

Pelagia Portal digitises the full purchase-order lifecycle — from a crew member raising a requisition aboard a vessel, through manager approval and payment by accounts, to receipt confirmation on delivery. It replaces paper and email-based processes with a traceable, role-gated workflow.

2. User Roles

Seven roles exist. Each role represents a real job function in the company.

Role Who they are Core capability
TECHNICAL Ship technical crew Create, submit, and track their own POs; confirm delivery
MANNING Manning crew Same as TECHNICAL
ACCOUNTS Finance / accounts team Process payments, manage vendor registry
MANAGER Department manager Review and approve POs, edit line items before approval, view analytics
SUPERUSER Power user / ops lead All PO actions across the board
AUDITOR Internal auditor Read-only view of all POs; export reports
ADMIN System administrator Manage users, vendors, vessels, accounts, products, and sites

Role Access Matrix

Feature area TECH / MANNING ACCOUNTS MANAGER SUPERUSER AUDITOR ADMIN
Create / edit own POs ✓ ✓ ✓
Approve / reject POs ✓ ✓
Process payments ✓ ✓
Confirm receipt ✓ ✓
View all POs ✓ ✓ ✓ ✓ ✓
View analytics / export ✓ ✓ ✓ ✓
Vendor registry ✓ ✓ ✓
Item catalogue ✓ ✓
Vessel management ✓ ✓
Site management ✓ ✓
User management ✓
Account management ✓ ✓

3. Navigation Structure

The left sidebar adapts to the signed-in user's role.

Dashboard                       ← all users

─── Purchase Orders ──────────────────
New PO                          ← TECH, MANNING, MANAGER, SUPERUSER
My Orders                       ← TECH, MANNING, MANAGER, SUPERUSER
Approvals                       ← MANAGER, SUPERUSER
Import PO                       ← MANAGER, SUPERUSER, ADMIN
Payments                        ← ACCOUNTS
History / Export                ← MANAGER, SUPERUSER, ACCOUNTS, AUDITOR, ADMIN

─── Inventory ───────────────────────
Vendors                         ← MANAGER, ACCOUNTS, ADMIN
Items                           ← MANAGER, ADMIN
Vessels                         ← MANAGER, ADMIN
Sites                           ← MANAGER, ADMIN
Cart                            ← TECH, MANNING, MANAGER, SUPERUSER

─── Administration ──────────────────  (ADMIN only)
Users
Accounts

4. Authentication

Login Page /login

  • Email + password form
  • Validates credentials against bcrypt hash
  • On success: redirects to /dashboard (or pre-login destination)
  • No self-registration; accounts are created by an ADMIN

5. Page Catalogue

5.1 Dashboard /dashboard

Entry point after login. Content varies by role.

Submitter view (TECHNICAL / MANNING / SUPERUSER)

  • Stat cards: Open orders count, Pending approval count, Completed orders
  • Quick "New PO" call-to-action
  • Link to full order list

Manager view

  • Stat cards: Awaiting approval (clickable → approval queue), Approved this month, Total approved spend
  • Recent approved POs table: PO number, title, vessel, amount, date
  • Spend trend chart (monthly bar chart, last 6–12 months)
  • Vessel spend breakdown chart (pie or bar)

Accounts view

  • Stat cards: Ready for payment count, Total value awaiting payment
  • Quick link to payment queue

Auditor / Admin view

  • Total PO count with link to history

5.2 My Purchase Orders /my-orders

Personal PO list for submitters.

Open orders table (DRAFT, SUBMITTED, MGR_REVIEW, VENDOR_ID_PENDING, EDITS_REQUESTED)

  • Columns: PO Number, Title, Vessel, Status badge, Amount, Last updated
  • Manager note displayed inline if status = EDITS_REQUESTED

Past orders table (MGR_APPROVED through CLOSED / REJECTED)

  • Same columns

Actions:

  • "New PO" button (top right)
  • Click any row → PO detail page

5.3 Approval Queue /approvals

All POs awaiting manager decision (status = MGR_REVIEW).

Filter bar:

  • Search (PO number, submitter name, title)
  • Vessel dropdown
  • Date from picker

Table columns: PO Number, Title, Submitter, Vessel, Amount, Submitted date

Actions:

  • "Review" link per row → approval detail page
  • Pending count shown in heading

5.4 PO Detail /po/[id]

Full read view of a single PO. Accessible to: the submitter (own POs), ACCOUNTS, MANAGER, SUPERUSER, AUDITOR, ADMIN.

Header band

  • PO number (monospace)
  • Status badge (colour-coded)
  • Export PDF button

Body sections

Summary panel

  • Title, vessel, account, vendor (if assigned), project code, date required, currency, total amount

Line items table

  • Columns: Item name, Description, Qty, Unit, Unit price, GST rate, Total (incl. GST)
  • Read-only

Terms & Conditions

  • Delivery, Dispatch, Inspection, Transit insurance, Payment terms, Others

Documents

  • Uploaded files with download links

Audit trail

  • Chronological list of every action on the PO
  • Each row: actor name, action type, timestamp, optional note

Timestamps sidebar (or footer)

  • Created, Submitted, Approved, Paid, Closed

Contextual action buttons (shown/hidden based on status and role)

Condition Button
Status = DRAFT or EDITS_REQUESTED + own submitter Edit
Status = DRAFT + own submitter or MANAGER/SUPERUSER Discard (delete draft)
Status = VENDOR_ID_PENDING + can provide vendor Vendor selection form inline
Status = PAID_DELIVERED + own submitter or SUPERUSER Confirm Receipt

5.5 Approval Detail /approvals/[id]

Full PO view with approval action panel. MANAGER / SUPERUSER only.

Same content as PO detail, plus:

Manager action panel

  • Approve button
  • Approve with Note button (opens note textarea, then approves)
  • Reject button (requires mandatory note)
  • Request Edits button (requires mandatory note)
  • Request Vendor ID button (sends back to submitter to supply vendor)

Manager line-item edit form

  • Inline form allowing manager to adjust quantities, unit prices, GST rate, add/remove line items and change vessel, account, vendor before approving

5.6 New PO /po/new

Multi-section form to create a purchase order.

Section 1 — Header

  • Title (required)
  • Description / remarks
  • Vessel (required, dropdown)
  • Account / Cost Centre (required, dropdown)
  • Vendor (optional, dropdown — can be added later)
  • Date Required (date picker)
  • Project Code

Section 2 — Line Items

  • Dynamic table; rows can be added and removed
  • Per-row fields: Name (searchable against item catalogue), Description, Qty, Unit, Size, Unit Price, GST Rate
  • As-you-type name search shows matching products with per-vendor prices as hints
  • Running totals shown below table: Taxable, GST, Grand Total

Section 3 — Terms & Conditions

  • Delivery, Dispatch, Inspection, Transit Insurance, Payment Terms, Others (all text, optional)

Section 4 — Documents

  • Drag-and-drop or browse file uploader
  • Shows list of attached files

Footer actions

  • Save as Draft
  • Submit for Approval

5.7 Edit PO /po/[id]/edit

Identical form to New PO, pre-filled with existing data.

Available only when status = DRAFT or EDITS_REQUESTED, and the user is the submitter or SUPERUSER.

Footer actions:

  • Save as Draft
  • Update & Resubmit (only shown when status = EDITS_REQUESTED; transitions back to MGR_REVIEW)

5.8 Import PO /po/import

Upload an Excel file in Pelagia's standard PO template format.

Steps (wizard-style or single page):

  1. Drop / upload .xlsx file
  2. System parses line items, vendor, quotation details
  3. User selects Vessel and Account (not parsed from file)
  4. Preview of extracted line items in editable table
  5. Save as Draft

5.9 Confirm Receipt /po/[id]/receipt

Receipt confirmation form. Shown only when status = PAID_DELIVERED.

  • PO number and title shown as context
  • File upload for delivery receipt document
  • Optional notes field
  • Submit button → transitions PAID_DELIVERED → CLOSED

5.10 Payment Queue /payments

ACCOUNTS role only.

Card list of POs in MGR_APPROVED and SENT_FOR_PAYMENT statuses.

Per card

  • PO number, title
  • Vessel, Submitter, Vendor
  • Approved date
  • Amount (prominent)
  • Status badge: "Ready for Payment" or "Processing — awaiting confirmation"

Per card actions

  • MGR_APPROVED → "Send for Payment" button
  • SENT_FOR_PAYMENT → "Mark as Paid" button
  • View PO detail link

5.11 History & Export /history

All POs in all statuses. MANAGER, SUPERUSER, ACCOUNTS, AUDITOR, ADMIN.

Filter bar

  • Date range (from / to)
  • Vessel dropdown
  • Status dropdown

Table columns: PO Number, Title, Vessel, Submitter, Status badge, Amount, Created date

Export buttons (apply current filters to export)

  • Export PDF
  • Export CSV

5.12 Vendor Registry /admin/vendors

Vendor list. MANAGER, ACCOUNTS, ADMIN.

Table columns: Vendor ID (or "Pending"), Name, Contact (name + email), Item count, Verified badge, Status badge

Actions

  • Add Vendor button → modal form (GSTIN lookup, name, address, pincode auto-filled via GST portal captcha; manual contact fields)
  • Edit / Delete per row
  • Click vendor name → Vendor Detail page

5.13 Vendor Detail /admin/vendors/[id]

Header

  • Vendor name, vendor ID, verified / active badges
  • Edit button

Info card

  • GSTIN, address, pincode, contact name, mobile, email

Items supplied table

  • Product code, name, last quoted price, last updated
  • Click product name → Item Detail page

Recent POs table

  • PO number, status, amount, created date (last 10)

5.14 GSTIN Lookup (modal / inline within vendor form)

Two-step flow embedded in the Add / Edit Vendor form:

  1. User types a 15-character GSTIN and clicks "Look up"
  2. System loads GST portal captcha image from the microservice → displays inline
  3. User types the 6-digit captcha answer
  4. User clicks "Verify" → microservice submits to GST portal → returns taxpayer data
  5. Form auto-fills: name, address, pincode (lat/lng geocoded silently from pincode)

Error states: wrong captcha (shows error, resets), session expired (auto-reset), GST portal unavailable.

5.15 Item Catalogue /admin/products

MANAGER, ADMIN.

Table columns: Name, Code, Description, Vendor count, Last price, Last vendor, Updated date, Status badge

Footer note: "Items are added automatically when a PO is marked as paid."

Actions (ADMIN only)

  • Add Product → modal form (code, name, description)
  • Toggle Active / Inactive per row
  • Delete per row
  • Click name → Item Detail page

5.16 Item Detail /admin/products/[id]

Header

  • Name, code, status badge, description
  • Add to Cart button
  • Toggle Active button (ADMIN only)

Stat cards

  • Vendor count, Lowest price, Highest price, Sites with stock

Price comparison bar chart

  • One bar per vendor, Y-axis = unit price

Site distance filter

  • Dropdown: "Sort by distance from site" — re-sorts vendor table by proximity
  • Uses geocoded pincode of vendor vs site lat/lng for distance

Vendor pricing table

  • Columns: Vendor (link to vendor detail), Verified badge, Unit price, Distance (if site selected), Last updated, Add to Cart
  • Closest vendor gets a ★ marker when a site is selected

Stock by site

  • Chip list: site name + quantity on hand (link to site detail)

5.17 Vessel Management /admin/vessels

MANAGER, ADMIN.

Table columns: Name, IMO Number, Status badge

Actions

  • Add / Edit / Delete per row (all modal)

5.18 Account / Cost Centre Management /admin/accounts

MANAGER, ADMIN.

Table columns: Code, Name, Description, Status badge

Actions

  • Add / Edit / Delete per row (all modal)

5.19 Sites /admin/sites

MANAGER, ADMIN (ADMIN-only for add/edit/delete).

Ports, depots, and offices that hold inventory.

Table columns: Name, Code, Address, Vessels, Items tracked, Location (lat/lon from pincode), Status badge

Actions

  • Add Site → modal form (name, code, address, pincode for auto-geocoding)
  • Edit / Delete per row
  • Click name → Site Detail page

5.20 Site Detail /admin/sites/[id]

Header

  • Name, code, address, geocoded location
  • Edit button (ADMIN only)

Stat cards

  • Vessels at site, Items tracked, Total inventory value (if calculable)

Inventory bar chart

  • X-axis = product name, Y-axis = quantity on hand

Consumption line chart

  • Last 30 days of daily consumption, one line per product

Inventory table

  • Product name, quantity on hand, last updated; link to item detail

Log consumption form

  • Fields: Product (dropdown), Date (date picker), Quantity, Note
  • Submits immediately; chart and table refresh

Assigned vessels

  • Chip list linking to vessel detail

Recent POs for this site

  • Last 8 POs with status, vendor, amount

5.21 User Management /admin/users

ADMIN only.

Table columns: Employee ID, Name, Email, Role badge, Status badge, Created date

Actions

  • Add User → modal form (employee ID, name, email, role, initial password)
  • Edit → modal form (same fields, password optional)
  • Delete per row

5.22 Cart /inventory/cart

Persistent cart collecting items selected from product detail pages. Stored in localStorage.

Cart view

  • Item list: product name, description, vendor (if selected), unit price, quantity (editable inline)
  • Summary: subtotal, GST, grand total
  • Site selector (to indicate delivery site)

Actions

  • Remove item
  • Clear cart
  • Create PO → opens New PO form pre-filled with cart line items and selected site/vendor

6. PO Lifecycle State Machine

                     ┌──────────────────────────┐
                     ▼                          │
[DRAFT] ──submit──► [SUBMITTED] ──auto──► [MGR_REVIEW]
                                              │  │  │  │
                              approve ◄───────┘  │  │  └──── reject ──► [REJECTED]
                              │                  │  │
                              │    request_edits─┘  └── request_vendor_id ──► [VENDOR_ID_PENDING]
                              │                                                       │
                              │         ◄──── provide_vendor_id ──────────────────────┘
                              │
                     [MGR_APPROVED]
                              │
                    process_payment
                              │
                     [SENT_FOR_PAYMENT]
                              │
                         mark_paid
                              │
                     [PAID_DELIVERED]
                              │
                    confirm_receipt
                              │
                          [CLOSED]

States that allow re-entry into the flow:

  • EDITS_REQUESTED → submitter edits PO → re-submits → MGR_REVIEW
  • VENDOR_ID_PENDING → submitter selects vendor → MGR_REVIEW

Terminal states: REJECTED, CLOSED

7. Workflows

7.1 Submit a Purchase Order (TECHNICAL / MANNING)

  1. Click New PO in sidebar
  2. Select vessel and account
  3. Add line items (type name to search item catalogue; previous vendor prices appear as hints)
  4. Optionally attach documents and fill in T&C fields
  5. Click Submit for Approval
  6. Manager receives email notification
  7. Status shows as "Under Review" on My Orders page
  8. If manager requests edits: submitter sees EDITS_REQUESTED status with manager note; edits form; resubmits
  9. If manager requests vendor ID: submitter selects a vendor and submits; returns to manager queue
  10. On approval: submitter notified by email; accounts team can see PO in payment queue

7.2 Approve a Purchase Order (MANAGER)

  1. Click Approvals in sidebar; see count of pending POs
  2. Click Review on a PO
  3. Read full detail: line items, vendor, documents, submitter notes
  4. Optionally: click Edit to adjust line items, change vendor, vessel, or account
  5. Choose action:
    • Approve → immediately moves to accounts payment queue
    • Approve with Note → same, with a note visible to submitter
    • Request Edits → write note explaining required changes; PO returned to submitter
    • Request Vendor ID → PO returned to submitter to select vendor; then returns to manager queue
    • Reject → write reason; PO is closed permanently

7.3 Process a Payment (ACCOUNTS)

  1. Click Payments in sidebar
  2. See cards for all MGR_APPROVED POs
  3. Click Send for Payment → initiates payment; notifies submitter and manager
  4. When payment is confirmed by bank/finance: click Mark as Paid → notifies all parties
  5. Submitter can now upload delivery receipt

7.4 Confirm Receipt (TECHNICAL / MANNING)

  1. Goods are delivered on site / to vessel
  2. Navigate to PO detail page (status = PAID_DELIVERED)
  3. Click Confirm Receipt
  4. Upload delivery receipt document and optionally add notes
  5. Submit → PO is CLOSED; accounts and manager notified

7.5 Look Up a Vendor by GSTIN (MANAGER / ADMIN)

  1. Open Add/Edit Vendor modal
  2. Type the 15-digit GSTIN
  3. Click Look up → captcha image loads from GST portal (via microservice)
  4. Type the 6-digit captcha shown in the image
  5. Click Verify → form auto-fills with legal name, trade name, registered address, pincode
  6. Review and save; location is geocoded silently from pincode for distance calculations

7.6 Source Items by Proximity (MANAGER)

  1. Navigate to Items → click an item name
  2. See all vendors that supply the item with their last quoted price
  3. Select a site from the "Sort by distance from" dropdown
  4. Table re-sorts: vendors nearest to the site appear first; distance shown per row; closest vendor marked ★
  5. Click Add to Cart on the desired vendor row → item added to cart

7.7 Create a PO from the Cart (MANAGER / TECHNICAL)

  1. Browse Item catalogue and add items to cart (Add to Cart button per vendor row)
  2. Click Cart in sidebar
  3. Review cart: adjust quantities inline; remove items; select delivery site
  4. Click Create PO → opens New PO form pre-filled with all cart items and vendor
  5. Fill in title, vessel, account; submit normally

7.8 Track Inventory at a Site (MANAGER / ADMIN)

  1. Navigate to Sites → click a site
  2. View bar chart of current stock (quantity per product)
  3. View consumption line chart (last 30 days)
  4. Use Log Consumption form to record daily drawdown: select product, pick date, enter quantity

7.9 Auto-sync Catalogue on Payment Confirmation (ACCOUNTS → SYSTEM)

When accounts clicks Mark as Paid:

  • System checks each PO line item that has a product link
  • For unlinked items: attempts fuzzy-match on name; creates new product record if no match
  • Upserts ProductVendorPrice — if this vendor/product combination is new or the price changed, updates the catalogue
  • Sets Product.lastPrice and Product.lastVendorId
  • Future POs using that product name will see this vendor's latest price as a hint

7.10 Import a PO from Excel (MANAGER)

  1. Navigate to Import PO
  2. Upload an Excel file in Pelagia's standard template format
  3. System extracts: line items (name, description, qty, unit, price, GST), vendor details, quotation number/date
  4. User selects vessel and account from dropdowns
  5. Review and optionally edit extracted line items
  6. Save as Draft → PO created; submitter can then edit and submit

7.11 Export PO History (AUDITOR / MANAGER)

  1. Navigate to History
  2. Apply filters: date range, vessel, status
  3. Click Export PDF or Export CSV
  4. File downloaded with all matching POs; up to 200 results per export

8. Data Entities

Purchase Order

Fields: PO number (auto-generated), title, status, total amount, currency, date required, project code, manager note, payment reference, quotation number/date, requisition number/date, place of delivery, all T&C text fields, timestamps.

PO Line Item

Fields: name, description, quantity, unit, size, unit price, GST rate (default 18%), total price (computed), sort order, optional product link.

Vendor

Fields: name, vendor ID (optional, unique), address, pincode, GSTIN, contact name/mobile/email, latitude/longitude (geocoded silently from pincode), verified flag, active flag.

Product (Item)

Fields: code (auto-generated or manual), name, description, last price, last vendor, active flag. Prices tracked per vendor via ProductVendorPrice (one record per product–vendor pair).

Vessel

Fields: name, IMO number (optional), active flag, assigned site (optional).

Site

Fields: name, code, address, pincode, latitude/longitude, active flag.

Account (Cost Centre)

Fields: code, name, description, active flag.

User

Fields: employee ID, email, name, role, active flag, password hash.

Inventory & Consumption

  • ItemInventory: quantity of a product at a site (one row per product–site pair)
  • ItemConsumption: daily draw-down record (one row per product–site–date)

9. Key UI Patterns

Status Badges

Each PO status has a distinct colour:

  • DRAFT — neutral grey
  • SUBMITTED / MGR_REVIEW — blue (in-progress)
  • VENDOR_ID_PENDING — orange/warning
  • EDITS_REQUESTED — yellow/warning
  • MGR_APPROVED — teal/success-adjacent
  • SENT_FOR_PAYMENT — purple
  • PAID_DELIVERED — blue-green
  • CLOSED — green/success
  • REJECTED — red/danger

Confirmation before Destructive Actions

Delete buttons use a two-step inline confirm: "Delete [name]? Confirm / Cancel". No modal dialog — the confirm state replaces the button in-place.

Inline Editing in Tables

Manager line-item editing in the approval flow happens in an inline form on the same page, not in a modal, so the manager can reference the rest of the PO while editing.

GST Calculation (always visible in PO forms)

Below the line-items table, a live summary shows:

  • Taxable amount (sum of qty × unit price)
  • GST amount (sum of qty × unit price × GST rate)
  • Grand Total (taxable + GST)

Product Autocomplete

In the PO line-item name field, typing triggers a fuzzy search of the item catalogue. Dropdown shows:

  • Product name and code
  • Price hints per vendor: "Vendor A: ₹1,200 · Vendor B: ₹1,050"

Cart Persistence

Cart is stored in browser localStorage under a fixed key. It survives navigation but is local to the device and user. A cart-updated custom event allows components to react to changes in real time.

Notifications / Emails

Every PO status transition triggers an email to relevant parties:

  • Submit → manager
  • Approve → submitter + accounts
  • Reject → submitter
  • Request Edits → submitter
  • Request Vendor ID → submitter
  • Payment sent → submitter + manager
  • Mark paid → submitter + manager
  • Receipt confirmed → manager + accounts

10. Non-Goals (Out of Scope)

  • Mobile app (web-only, desktop-first)
  • Public-facing pages (entirely internal)
  • Self-registration / OAuth login
  • Vendor portal (vendors do not log in)
  • Automated bank/payment-gateway integration (payment is marked manually)