pelagia-portal/DESIGN.md

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