KES Extraction Prep Map

Historical Status Note

This document records the pre-extraction KES boundary as it existed before svc-kes became the canonical KES HTTP/runtime host.

Current truth:

• canonical KES runtime: services/svc-kes
• retired host: old colocated KES HTTP routing in svc-tenders
• removed compatibility layer: former services/svc-tenders/src/kes/*
• retained shared backbone: services/svc-tenders/src/kafka

References below to registerKesRoutes.ts, kesRouteSupport.ts, or services/svc-tenders/src/kes/* are historical extraction-prep evidence, not current live topology.

Scope

This document defines the current real extraction boundary for KES inside services/svc-tenders.

It does not assume KES is already cleanly separable. It reflects current code truth.

High-Level Verdict

• VERIFIED: KES is a real backend operational domain, not a UI shell.
• VERIFIED: KES is more shell-heavy than ICPI, Accommodation, Vacancy, or Butkhuzi were at their first extraction-prep pass.
• VERIFIED: the strongest current KES backend surface is the orchestrator case/task/inspection/payment lifecycle plus control-plane and projection reads.
• VERIFIED: KES is also where shared Kvary event-backbone and ingress-security concerns become part of the extraction story.
• VERIFIED: the gateway seam already exists in kes-orchestrator.ts, so KES is not blocked on API-first work.
• VERIFIED: KES is blocked primarily by mixed repository ownership, shared shell ingress helpers, and Kafka/outbox coupling.

Current KES-Owned Modules

| Surface | Current location | Confidence | State | Ownership | Notes | | --- | --- | --- | --- | --- | --- | | KES route flow module | registerKesRoutes.ts | VERIFIED | REAL | KES-owned, temporary-hosted-in-svc-tenders | Real route cluster for case entry, public reads, control-plane, process-map, tasks, inspections, payments, and closure | | KES route support assembly | kesRouteSupport.ts | VERIFIED | MIXED | temporary-hosted-in-svc-tenders, shared shell / ingress-owned | Structurally isolated, but mostly forwards shell auth/parser helpers plus KES ingress helpers | | KES control-plane reads | registerKesRoutes.ts | VERIFIED | REAL | KES-owned | GET /kes-orchestrator/control-plane is a real read surface built from case/projection/detail fan-out | | KES process-map reads and mutation | registerKesRoutes.ts, repository.ts | VERIFIED | REAL | KES-owned | Process-map config is durable and KES-specific, but still stored through the mixed root repository | | KES case/task/inspection/payment lifecycle | repository.ts | VERIFIED | REAL | KES-owned, temporary-hosted-in-svc-tenders | Core orchestration state machine lives here today | | KES case projection shaping | repository.ts | VERIFIED | REAL | KES-owned | Projection is computed from KES detail, not borrowed from another domain | | KES validation schemas | validation.ts | VERIFIED | MIXED | KES-owned, temporary-hosted-in-svc-tenders | Clearly KES-owned logic, but still hosted in the mixed root validation file | | KES route-local helper cluster | registerKesRoutes.ts | VERIFIED | REAL | KES-owned | List-option parsing, role parsing, state parsing, ID generation |

Shared Dependencies

| Surface | Current location | Confidence | State | Ownership | Notes | | --- | --- | --- | --- | --- | --- | | Bearer auth and principal resolution | server.ts | VERIFIED | REAL | shared-Kvary-owned, shared shell / ingress-owned | requireServiceAuth(...) and /auth/me principal resolution stay outside KES today | | KYC boundary gate | server.ts | VERIFIED | REAL | shared shell / ingress-owned | ensureThirdPartyKycBoundary(...) is KES-facing but still a shell ingress helper | | Signature verification gate | server.ts | VERIFIED | REAL | shared shell / ingress-owned | verifyIncomingSignatureGate(...) is route-boundary security, not yet KES-owned | | API gateway seam | kes-orchestrator.ts | VERIFIED | REAL | shared-Kvary-owned | KES_ORCHESTRATOR_SERVICE_URL ?? TENDERS_SERVICE_URL is already extraction-friendly | | Kafka proxy mutation producer | kes-orchestrator.ts | VERIFIED | REAL | kafka/orchestrator-shared | Gateway publishes mutation envelopes after non-GET KES calls | | Outbox relay, projection consumer, idempotency, DLQ tooling | services/svc-tenders/src/kafka | VERIFIED | REAL | kafka/orchestrator-shared | KES is the main user, but these pieces behave like shared event-backbone runtime concerns |

Temporary Hosting Points

| Surface | Current location | Confidence | State | Ownership | Notes | | --- | --- | --- | --- | --- | --- | | Durable KES persistence methods | repository.ts | VERIFIED | MIXED | temporary-hosted-in-svc-tenders | KES persistence is real, but not yet extracted into a KES-owned repository module | | KES contracts and types | repository.ts | VERIFIED | MIXED | temporary-hosted-in-svc-tenders | KES types are defined alongside unrelated repository types | | KES validation | validation.ts | VERIFIED | MIXED | temporary-hosted-in-svc-tenders | One of the cleanest future hardening targets | | Server-owned ingress helpers | server.ts | VERIFIED | MIXED | shared shell / ingress-owned | KES depends on them, but they are not yet wrapped into a cleaner shared contract |

Web / Client Truth

• VERIFIED: the real backend-facing KES consumer is apps/web/src/portal/api.ts, which calls /kes/orchestrator/*.
• VERIFIED: KesControlPlaneView.tsx uses those real control-plane and detail reads.
• VERIFIED: the broader KES workspace/editor page in page.tsx is heavily localStorage-backed and therefore UI-FIRST, not proof of extracted-backend readiness.
• VERIFIED: KES web truth is asymmetric:
  • orchestrator/control-plane reads are real backend consumers
  • workspace/editor behavior is still materially UI-hosted

Minimum Credible KES Extraction Package

Move-first package:

• registerKesRoutes.ts
• kesRouteSupport.ts
• the KES schema block currently in validation.ts
• the KES contracts and persistence slice currently in repository.ts
• KES-specific projection and hash-chain logic currently embedded in repository.ts

Likely shared at first:

• gateway route family in kes-orchestrator.ts
• auth ingress and /auth/me principal resolution
• KYC boundary and signature gate helpers
• event envelope contract in kesEventSchema.ts

Likely deferred or split later:

• outbox relay
• domain-event consumer
• idempotency store
• DLQ replay tooling

Those are too entangled with shared event-backbone responsibility to assume a simple first move.

Extraction Blockers

| Blocker | Severity | Type | Why it blocks | What reduces it next | | --- | --- | --- | --- | --- | | Mixed root repository ownership | HIGH | code-only | KES persistence, contracts, and projections still live inside the giant root repository file | carve out a KES-owned repository/contracts module first | | Shared ingress/security coupling | HIGH | code-only | payment-sensitive routes depend on shell-owned KYC and signature helpers from server.ts | define a KES shared-shell contract and wrap those helpers explicitly | | Root validation hosting | MEDIUM | code-only | KES validation is clearly domain-specific but still lives in mixed validation.ts | move KES schemas into a domain-owned validation file | | Kafka/outbox coupling | HIGH | code+infra | KES route extraction alone does not settle relay, projection consumer, DLQ, or idempotency ownership | classify which event workers move with KES and which stay shared | | Payment-note encryption and hash-chain logic embedded in repository | MEDIUM | code-only | payment-sensitive behavior is mixed into the root repository implementation | extract KES payment/integrity submodule with explicit dependencies | | Web asymmetry | MEDIUM | code-only | control-plane is real backend; workspace/editor is still UI-hosted | keep UI-first workspace out of the initial runtime boundary | | Migration ownership ambiguity | HIGH | code+infra | KES tables, outbox tables, and projection tables are tightly related but not all are pure KES-only ownership | separate KES core tables from shared event-backbone tables before runtime prep |

Recommended Extraction Direction

• VERIFIED: KES should not start with runtime-first extraction.
• VERIFIED: the safest next direction is package-first hardening:
  • move KES validation out of root validation.ts
  • isolate KES contracts/types from root repository.ts
  • define a truthful shared-shell contract for auth, KYC, signature verification, and gateway behavior
  • classify event-backbone pieces as shared vs KES-move candidates
• VERIFIED: only after that should runtime/bootstrap prep begin.