Master-Data Performance, Postgres on Staging & Azure Swap Feasibility

Outcome

Staging runs on Postgres so every change is validated against the production engine. Huy does all the work on staging only and produces a written procedure; Quang later applies that procedure in production. Huy does not log into the production database or production servers.

Work items

• Swap the database adapter in the app from SQLite to Postgres.
• Generate an initial Postgres schema + migration.
• Port the master-data search backend to Postgres. src/search/searchService.ts (~250 lines) and src/search/sqliteClient.ts are SQLite-specific raw SQL (json_extract, @libsql/client) — they stop working the moment the adapter switches. Rewrite the JSON-path SQL with Postgres JSONB operators and replace the libsql client with a pg wrapper. Without this, the master-data routes are broken on staging.
• Provision a Postgres instance for the staging Azure App Service (e.g. Azure Database for PostgreSQL Flexible Server), configure the App Service's outbound access to it, and set DATABASE_URI with sslmode=require in the staging slot's app settings.
• Run migrations and re-import master data on staging (the existing test/migrate-to-pg.ts script already covers this).
• Smoke-test landing, admin, and the master-data endpoints on staging.
• Produce a written production handover document for Quang covering: Postgres provisioning, network access, env-var configuration, migration command to run, data restore from the existing backup scripts, smoke checklist, and rollback path.

Deliverables

• App running on Postgres in staging.
• Initial Postgres migration committed to the repo.
• docs/postgres-production-handover.md — the production checklist for Quang.

Outcome

The expensive part of the master-data search route is not the WHERE/COUNT query (that is already raw SQL in searchService.ts) — it is the payload.find({ where: { id: { in: ids } }, depth: 1 }) hydration step in src/app/api/master-data/search/route.ts:55-61 which runs all relationship-resolution and field hooks for every paged row. Replace that one call with direct SQL hydration so the route does no Payload-ORM work on the hot path. A unit-test suite is added and made a mandatory gate on every deploy — no path to staging or production that skips tests.

Endpoints in scope (read paths only)

• GET /api/master-data/search
• GET /api/master-data/versions
• GET /api/master-data/facet-values

Writes (admin edits, imports) stay on Payload — they need hooks and validation.

Work items

• Replace the payload.find({ where: { id: { in: ids } }, depth: 1 }) hydration step in search/route.ts with direct SQL hydration that loads the row + its depth: 1 relations per collection. There are 18 master-data collections in masterDataCatalog, each with different relation fields — hydration logic has to cover all of them.
• Preserve the existing response shape so WPA and the admin UI need no changes.
• Keep the existing auth check on each route.
• Set up a real unit-test layer — currently absent. The repo's test/ folder is ad-hoc benchmark scripts; vitest's include points at tests/int/**/*.int.spec.ts which does not exist yet.
• One spec per route covering: response shape, filter / pagination correctness, auth rejection (401), and input validation (400).
• Add a shared fixture loader that seeds a minimal master-data dataset (one coding system + a handful of rows across the catalogued collections) — Payload boot is slow, so the loader needs to run once per suite, not per test.
• Add a mandatory test gate to the Azure App Service deploy pipeline: run pnpm test:int before the build/publish step — non-zero exit aborts the deploy and the previous slot keeps serving traffic.
• Apply the same gate to the future production deploy path documented in T1.

Deliverables

• Hydration step in search/route.ts rewritten as direct SQL, covering all 18 catalogued collections; same response contract.
• Unit-test suite for the three master-data routes, runnable via pnpm test:int.
• Updated deploy path that fails fast on a red test run.

Outcome

A clear yes/no on whether this app can use Azure deployment-slot swap for near-zero-downtime releases, plus the artifacts needed to act on the answer. As with the other tasks, Huy researches and prepares the app on staging only; the actual swap setup in the production Azure subscription is owned by Quang, following the runbook Huy writes.

Phase 1 — Research spike (always happens)

• Audit every place the app holds state on local disk (DB file, media uploads, generated caches, sitemap, logs).
• Audit env-var usage to identify which values must be slot-pinned vs. swappable.
• Review startup behavior against App Service's warmup window.
• Produce a written feasibility verdict.

Phase 1 estimate: 4h