Vendors and GST Lookup

Vendors are suppliers a PO can be raised against. The model and its evolution are on Data Model; this page covers the verification lifecycle, distance-based sourcing, and the GST microservice that backs GSTIN lookup.

Vendor verification lifecycle

created (unverified) ──▶ verified
   ▲                         ▲
   │ submitter adds          │ PO closes/pays with vendor
   │ (create_vendor)         │ • on import
   │                         │ • Manager/Accounts/Admin verifies

Submitters can create vendors (create_vendor is held by TECH/MANNING too) but they are created isVerified = false.
A vendor becomes verified when a PO is closed/paid with it, on import, or when a manage_vendors holder (Manager/Accounts/Admin) verifies it.
Only manage_vendors holders may assign the formal verified vendorId code.
A vendor must be assigned before a manager can approve a PO, and only verified vendors may be assigned via provideVendorId.

A vendor carries gstin, address, pincode, geocoded latitude/longitude, and a VendorContact[] list (name, role, mobile, email, isPrimary). Managed at /admin/vendors; read view at /inventory/vendors/[id].

Distance-based sourcing

pincode is geocoded to latitude/longitude (lib/geo.ts). On the item detail / items pages, selecting a Site re-sorts vendors by proximity to that site; the nearest vendor gets a ★ Closest tag and the lowest price gets a Cheapest tag — computed independently so both can show at once, regardless of the active sort. See Inventory and Catalogue.

GSTIN lookup (GstService)

GSTIN lookup auto-fills a vendor's legal name, address, and pincode from the public GST portal. Because that portal is CAPTCHA-protected, a small sidecar microservice drives it with a headless browser.

The microservice

GstService/ — an Express + Playwright service (GstService/src/index.ts). It opens a Playwright session against services.gst.gov.in, surfaces the portal CAPTCHA, and submits the GSTIN + CAPTCHA answer to return taxpayer details.

Endpoint	Method	Purpose
`/health`	GET	Liveness check
`/captcha`	GET	Start a session; return a fresh CAPTCHA image + `sessionId`
`/captcha/:sessionId`	GET	Refresh the CAPTCHA within an existing session (no reload)
`/search`	POST	Submit GSTIN + CAPTCHA answer; return taxpayer data

Port: PORT env, default 3003.
Run: cd GstService && pnpm dev (or npm run dev) — tsx watch src/index.ts.

The portal proxy

The Next.js app proxies to it so the browser never talks to the GST portal directly:

/api/gst/captcha (GET) → CAPTCHA image / session
/api/gst (POST) → taxpayer search

The base URL is GST_SERVICE_URL (default http://localhost:3003).

Lookup flow (in the Add/Edit Vendor form)

User types a 15-char GSTIN and clicks Look up.
The CAPTCHA image loads inline from the microservice.
User types the 6-digit CAPTCHA answer and clicks Verify.
The microservice submits to the GST portal and returns name, trade name, registered address, and pincode.
The form auto-fills; location is geocoded silently from the pincode for distance calculations.

Error states handled: wrong CAPTCHA (shows error, resets), session expired (auto-reset / refresh CAPTCHA), GST portal unavailable.

The GstService is tested independently and is out of scope for the portal's E2E suite. It is optional in local dev unless you are exercising GSTIN lookup.

Pelagia Portal (PPMS)

Home

Overview

Build & Run

System

Product

Planned

Quality

Ops

Engineering

Tech Debt

Pelagia Portal (PPMS) — internal purchase-order management. Self-hosted on pms1, live at pms.pelagiamarine.com. This wiki tracks the shipped product; authoritative sources are the repo code, App/CLAUDE.md, Docs/, and CHANGELOG.md.