From 2bf044404ebd0a7e7afa69cd9eccbcf41d30e83d Mon Sep 17 00:00:00 2001
From: shad0w <shardik99@gmail.com>
Date: Wed, 24 Jun 2026 10:03:03 +0000
Subject: [PATCH] docs: add Microservices section (gst/epfo/pdf)

---
 Deployment-and-Operations.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/Deployment-and-Operations.md b/Deployment-and-Operations.md
index 43e3a7f..6882bf7 100644
--- a/Deployment-and-Operations.md
+++ b/Deployment-and-Operations.md
@@ -39,6 +39,32 @@ All production env vars must be set (auth, DB, R2, Resend, optionally
 Forgejo/GST). Server-side env lives in `~/pms/App/.env`. The full list and the
 dev/prod split is on [Environment Variables](Environment-Variables).
 
+## Microservices
+
+Three standalone **Express + Playwright** services run alongside the app on
+pms1, each on a fixed local port, reached by the app over `localhost`:
+
+| Service | pm2 name | Port | Purpose | App env |
+|---|---|:--:|---|---|
+| GstService | `gst-service` | 3003 | GSTIN lookup for vendors | `GST_SERVICE_URL` |
+| EpfoService | `epfo-service` | 3004 | UAN / EPFO member lookup (crewing) | `EPFO_SERVICE_URL`, `EPFO_LIVE` |
+| PdfService | `pdf-service` | 3005 | Renders a PO to PDF for “Email to vendor” | `PDF_SERVICE_URL`, `PDF_SERVICE_TOKEN`, `APP_INTERNAL_URL` |
+
+They are **auto-deployed on release** by the root `ecosystem.config.js` +
+`.forgejo/workflows/deploy.yml`: the deploy builds each service that is checked
+out, exports the few keys they need out of `App/.env` (e.g. `PDF_SERVICE_TOKEN`,
+`EPFO_LIVE`), then `pm2 startOrReload ecosystem.config.js --update-env` (creates
+them on first release, reloads after). Unset secrets fall back to harmless
+defaults (GST/EPFO stay stub-capable; PdfService skips token checks).
+
+**Email PO to vendor (PdfService).** Enabled by setting `PDF_SERVICE_URL` +
+`PDF_SERVICE_TOKEN` in `~/pms/App/.env` (gate `isPdfServiceConfigured()`); the
+**same token must reach `pdf-service`** (the deploy exports it). PdfService
+renders the app's `/api/po/<id>/export?…&svc=<token>` page (the token lets it
+fetch without a user session), uploads the PDF to R2, and the app returns a
+`mailto:` with a **7-day** presigned link. `APP_INTERNAL_URL` is the URL
+PdfService uses to reach the app (defaults to `NEXTAUTH_URL`).
+
 ## Release & deploy flow
 
 Deploys are **gated on a human merging a PR and pushing a release tag**.