ICPI Handoff Plan

Goal

This plan defines the safest real sequence for lifting ICPI out of svc-tenders while keeping:

• gateway behavior unchanged
• auth behavior unchanged
• route contracts unchanged

Shared Shell Contract

ICPI should continue to rely on a very small shared shell during and immediately after extraction:

• gateway proxying in services/api/src/routes/icpi.ts
• gateway auth middleware in services/api/src/auth/middleware.ts
• shared auth/identity resolution behind service-side auth ingress

Everything else should be treated as ICPI-owned move material unless later evidence says otherwise.

Safest Extraction Sequence

1. Create the new ICPI-owned runtime/package location

Move or copy first:

• services/svc-tenders/src/icpi/contracts.ts
• services/svc-tenders/src/icpi/queryParsers.ts
• services/svc-tenders/src/icpi/validation.ts
• services/svc-tenders/src/icpi/repository.ts
• services/svc-tenders/src/routes/registerIcpiRoutes.ts
• services/svc-tenders/src/routes/support/icpiRouteSupport.ts
• ICPI migrations 0007 and 0008

Do not change route shapes at this step.

2. Add an ICPI-local runtime bootstrap

Create the smallest possible runtime shell for the extracted ICPI host:

• Express app bootstrap
• DB pool bootstrap
• ICPI repository construction
• ICPI route registration
• service-side auth ingress equivalent to current requireServiceAuth

This is the first step that replaces temporary hosting in svc-tenders.

3. Keep the gateway seam unchanged

Do not change:

• services/api/src/routes/icpi.ts paths
• GET /api/v1/icpi/*
• POST /api/v1/icpi/upsert
• gateway auth behavior

Only change the target behind ICPI_SERVICE_URL.

4. Point the gateway to the new ICPI runtime

Deployment cutover should prefer:

• ICPI_SERVICE_URL=<new-icpi-runtime>

while leaving:

• TENDERS_SERVICE_URL

unchanged for other domains.

The fallback shape in services/api/src/routes/icpi.ts means rollback remains easy as long as the old colocated host still exists.

5. Verify parity while old colocated ICPI host still exists

During the first cutover window:

• keep the old svc-tenders ICPI host available
• route public traffic through the gateway to the new ICPI runtime
• compare behavior against the old host if needed

6. Remove old colocated ICPI hosting

Only after parity is proven:

• remove ICPI registration from services/svc-tenders/src/server.ts
• remove any now-unused ICPI support wiring from svc-tenders
• remove old colocated ICPI config residue if it becomes dead

Cutover Checklist

Code moved

• ICPI contracts
• ICPI query parsers
• ICPI validation
• ICPI repository
• ICPI route registration
• ICPI support assembly
• ICPI migrations

Imports updated

• new runtime imports point to moved ICPI modules
• gateway imports remain unchanged
• web imports remain unchanged

Env variables required

• ICPI_SERVICE_URL
• ICPI_PROXY_TIMEOUT_MS
• extracted ICPI runtime equivalents for:
  • DATABASE_URL
  • JWT_SECRET
  • AUTH_SERVICE_URL
  • PORT

Route parity checks

• GET /api/v1/icpi/prices
• GET /api/v1/icpi/suggest
• GET /api/v1/icpi/latest/:itemCode
• GET /api/v1/icpi/estimate
• POST /api/v1/icpi/upsert

Behavior parity checks

• same 200 / 400 / 404 behavior
• same JSON response shapes
• same reasonCode values for current known failures
• same pagination behavior
• same upsert normalization and dedupe behavior

Auth parity checks

• gateway still blocks unauthenticated upsert
• extracted service still verifies bearer token the same way
• extracted service still resolves principal through shared auth service

Build / verification checks

• extracted ICPI runtime build passes
• services/api build passes
• current svc-tenders build still passes during staged migration

Rollback Plan

The rollback path should be operationally simple:

1. point ICPI_SERVICE_URL back to the old colocated host, or unset it so gateway falls back to TENDERS_SERVICE_URL
2. redeploy or reload the gateway environment
3. leave the extracted ICPI runtime stopped or isolated
4. keep the old svc-tenders ICPI route registration intact until cutover confidence is high

This is why old colocated ICPI hosting should not be removed in the same first step as the initial gateway cutover.

What To Monitor After Cutover

• gateway 502 / 504 rates for /api/v1/icpi/*
• 401 behavior for POST /api/v1/icpi/upsert
• latency on prices, suggest, latest, and estimate
• DB error rates on ICPI reads and upsert
• route-shape mismatches visible in web ICPI page failures

Main Risks

• auth-ingress drift between the old svc-tenders implementation and the new ICPI host
• unnoticed request/response contract drift on the web-facing ICPI endpoints
• missing env wiring for ICPI_SERVICE_URL, JWT_SECRET, or AUTH_SERVICE_URL
• leaving web/service ICPI type duplication unmanaged long enough for drift to accumulate