services/api Responsibility Map

Status: ACTIVE
Audit Date: 2026-03-16
Cleanup Sprint: 01

Purpose

This document classifies services/api route/modules by actual responsibility.

Use these labels:

• gateway
• façade
• fallback
• mock/fixture
• compatibility
• should-move-later

Module Map

| Module | Classification | State | Notes | | --- | --- | --- | --- | | services/api/src/routes/auth.ts | gateway + façade | REAL | mostly proxies to svc-auth, but /me is gateway-composed | | services/api/src/routes/profile.ts | gateway | REAL | profile proxy to auth service | | services/api/src/routes/risk.ts | gateway | REAL | direct service façade | | services/api/src/routes/icpi.ts | gateway | REAL | direct svc-tenders façade | | services/api/src/routes/butkhuzi.ts | gateway | REAL | direct svc-tenders façade | | services/api/src/routes/kes-orchestrator.ts | façade + eventing edge | REAL | proxies to svc-tenders and emits Kafka proxy events | | services/api/src/routes/kes.ts | façade | MIXED | KES-related surface, not the durable event backbone itself | | services/api/src/routes/stakeholder-context.ts | gateway | REAL | proxies stakeholder context reads | | services/api/src/routes/land-owner-onboarding.ts | gateway | REAL | proxies onboarding mutation subflows | | services/api/src/routes/stakeholder-applications.ts | façade + partial stub | MIXED | draft/submit/events/projection proxied; reviewer actions stubbed | | services/api/src/routes/tenders.ts | gateway + compatibility | MIXED | modern proxy routes plus mounted legacy flow | | services/api/src/tenders/gateway.ts | fallback | MIXED | upstream proxy plus read fallback for list/detail | | services/api/src/tenders/legacyRoutes.ts | compatibility route shell | MIXED | mounts legacy local-engine actions and keeps route-level compatibility behavior explicit | | services/api/src/tenders/legacyBridge.ts | compatibility bridge | MIXED | gateway-side legacy outbox enqueue bridge used by tender legacy routes | | services/api/src/tenders/engine.ts | should-move-later | UI-FIRST | local legacy domain engine, not canonical public truth | | services/api/src/routes/auctions.ts | gateway + fallback surface | MIXED | read proxy plus mounted local engine | | services/api/src/auctions/gateway.ts | fallback | MIXED | upstream read proxy and local-engine fallback helpers | | services/api/src/auctions/localEngineRoutes.ts | fallback + compatibility | MIXED | local action flow for create/open/bid/award/settle | | services/api/src/auctions/engine.ts | should-move-later | UI-FIRST | local auction engine, not canonical service-owned action path | | services/api/src/routes/map.ts | mock/fixture | SHELL | fixture-backed projection endpoint | | services/api/src/routes/stakeholders.ts | mock/fixture | SHELL | fixture-backed stakeholder /me | | services/api/src/routes/registerApiV1Routes.ts | façade composition | REAL | cleanup sprint grouping layer | | services/api/src/server.ts | runtime boot | REAL | now thin bootstrap only |

Route Family Classification

Gateway

• /api/v1/auth/*
• /api/v1/profile/*
• /api/v1/risk/*
• /api/v1/icpi/*
• /api/v1/butkhuzi/*
• /api/v1/stakeholder-context/*
• onboarding mutation subpaths under /api/v1/stakeholder-applications/:id/*

Façade

• /api/v1/kes/orchestrator/*
• /api/v1/stakeholder-applications/*

Reason:

• gateway policy/auth composition is added on top of upstreams

Fallback

• /api/v1/auctions
• /api/v1/auctions/:id
• /api/v1/tenders
• /api/v1/tenders/:id

Reason:

• read proxy first, local fallback second

Compatibility

• /api/v1/tenders/legacy/*

Compatibility Bridge

• gateway-side legacy outbox enqueue helper in services/api/src/tenders/legacyBridge.ts, called by /api/v1/tenders/legacy/*

Mock / Fixture

• /api/v1/map/overview
• /api/v1/stakeholders/me

Cleanup Sprint 01 Changes

• Split routes/auctions.ts into:
  • services/api/src/auctions/gateway.ts
  • services/api/src/auctions/localEngineRoutes.ts
• Split routes/tenders.ts into:
  • services/api/src/tenders/gateway.ts
  • services/api/src/tenders/legacyRoutes.ts
• Moved route registration grouping into:
  • services/api/src/routes/registerApiV1Routes.ts

Should Move Later

• services/api/src/auctions/engine.ts
• services/api/src/tenders/engine.ts
• fixture-driven map and stakeholders routes

Reason:

• these are useful scaffolds, but they should remain explicitly non-canonical until replaced.