API Auction Tender Boundary Status

Scope

This document describes the current services/api boundary for auctions and tenders.

It separates:

• canonical upstream proxy routes
• gateway-local compatibility routes
• legacy local-engine routes
• gateway-emitted legacy tender event behavior

It does not claim that auction/tender extraction is already done.

Auction Route / Path Classification

| Public route/path | Current classification | Current behavior | Notes | | --- | --- | --- | --- | | GET /api/v1/auctions | canonical upstream proxy with temporary gateway-local compatibility fallback | tries upstream via auctions/gateway.ts, falls back to local list projection from auctions/engine.ts | response headers expose whether source was upstream or gateway-local | | GET /api/v1/auctions/:id | canonical upstream proxy with temporary gateway-local compatibility fallback | same pattern as list route | local fallback still uses gateway viewer/fixture logic | | POST /api/v1/auctions/create | temporary gateway-local compatibility path | executes registerAuctionLocalEngineRoutes against the local engine | not canonical durable backend | | POST /api/v1/auctions/:id/announce | temporary gateway-local compatibility path | gateway-local action | not canonical durable backend | | POST /api/v1/auctions/:id/open | temporary gateway-local compatibility path | gateway-local action | not canonical durable backend | | POST /api/v1/auctions/:id/bids | temporary gateway-local compatibility path | gateway-local action | not canonical durable backend | | POST /api/v1/auctions/:id/close | temporary gateway-local compatibility path | gateway-local action | not canonical durable backend | | POST /api/v1/auctions/:id/award | temporary gateway-local compatibility path | gateway-local action | not canonical durable backend | | POST /api/v1/auctions/:id/settle | temporary gateway-local compatibility path | gateway-local action | not canonical durable backend |

Tender Route / Path Classification

| Public route/path | Current classification | Current behavior | Notes | | --- | --- | --- | --- | | GET /api/v1/tenders | canonical upstream proxy with temporary gateway-local compatibility fallback | proxies upstream first through tenders/gateway.ts; on fetch failure, falls back to gateway-local legacy list projection | fallback is read-only and compatibility-only | | GET /api/v1/tenders/:id | canonical upstream proxy with temporary gateway-local compatibility fallback | same pattern as list route | fallback uses gateway-local legacy tender projection | | POST /api/v1/tenders/submit | canonical upstream proxy | no local-engine fallback | canonical public tender submit path | | GET /api/v1/tenders/me | canonical upstream proxy | no local-engine fallback | auth-guarded upstream proxy | | GET /api/v1/tenders/admin/queue | canonical upstream proxy | no local-engine fallback | auth/policy-gated upstream proxy | | POST /api/v1/tenders/admin/:id/approve | canonical upstream proxy | no local-engine fallback | auth/policy-gated upstream proxy | | POST /api/v1/tenders/admin/:id/reject | canonical upstream proxy | no local-engine fallback | auth/policy-gated upstream proxy | | POST /api/v1/tenders/legacy/propose | legacy local-engine path | executes gateway-local legacy tender action | may emit legacy tender outbox event | | POST /api/v1/tenders/legacy/:id/bids | legacy local-engine path | executes gateway-local legacy tender action | may emit legacy tender outbox event | | POST /api/v1/tenders/legacy/:id/close | legacy local-engine path | executes gateway-local legacy tender action | may emit legacy tender outbox event | | POST /api/v1/tenders/legacy/:id/award/propose | legacy local-engine path | executes gateway-local legacy tender action | may emit legacy tender outbox event | | POST /api/v1/tenders/legacy/:id/award/ratify | legacy local-engine path | executes gateway-local legacy tender action | may emit legacy tender outbox event |

Gateway-Emitted Legacy Tender Event Behavior

The tender legacy path has an extra boundary concern beyond route handling:

• tenders/legacyRoutes.ts can emit legacy outbox events to TENDERS_SERVICE_URL
• target path: LEGACY_TENDERS_OUTBOX_PATH, default /legacy/tenders/events
• event types:
  • TENDER_CREATED
  • BID_SUBMITTED
  • BIDDING_CLOSED
  • AWARD_PROPOSED
  • AWARD_RATIFIED

Classification:

• gateway-side event emission path
• legacy compatibility behavior
• not the canonical durable tender boundary

Canonical Upstream Vs Local Split

Canonical upstream today

• auction read proxy attempts through auctions/gateway.ts
• tender public/admin routes through tenders/gateway.ts

Temporary compatibility behavior

• auction read fallback to gateway-local projection logic
• tender read fallback to gateway-local legacy projection logic
• local-engine source headers that explicitly label compatibility behavior

Legacy local-engine behavior

• auction public mutation routes mounted from localEngineRoutes.ts
• tender /legacy/* routes mounted from legacyRoutes.ts

What Remains Temporary

• auction local-engine action routes
• tender read fallback to the gateway-local legacy engine
• tender /legacy/* routes
• gateway-emitted legacy tender outbox events
• fixture/example-backed gateway viewer assumptions inside the local-engine path

What Should Be Cleaned Next

The strongest follow-on cleanup target is:

• the separation between canonical upstream auction/tender ownership and gateway-local compatibility behavior

That next step should:

• keep route shape stable
• classify which local-engine paths are compatibility-only and how long they stay
• decide whether auction mutations and legacy tender actions should continue living in the gateway at all

Notes

• This boundary is now explicit enough for the next sprint to work surgically.
• The main blocker for deeper auction/tender extraction is not missing runtime files. It is this still-mixed API boundary.