Butkhuzi Extraction Prep Map

This document defines the current Butkhuzi extraction boundary from code truth.

It does not assume a standalone runtime already exists.

High-level verdict

• VERIFIED: Butkhuzi is a real backend subdomain today.
• VERIFIED: the cleanest current Butkhuzi core is norms storage plus chunk-backed search/suggest and admin ingest.
• VERIFIED: the public/API seam is already favorable for extraction because services/api/src/routes/butkhuzi.ts uses BUTKHUZI_SERVICE_URL ?? TENDERS_SERVICE_URL.
• VERIFIED: Butkhuzi is still temporarily hosted in svc-tenders.
• VERIFIED: current product use is KES/admin-adjacent rather than a fully independent platform UX.
• VERIFIED: Butkhuzi is closer to ICPI-style extraction readiness than Vacancy/Accommodation were, but it still carries shared-shell and mixed-contract residue.

Current Butkhuzi-owned modules

| Surface | Current location | Confidence | State | Ownership | Notes | | --- | --- | --- | --- | --- | --- | | Route registration | services/svc-tenders/src/routes/registerButkhuziRoutes.ts | VERIFIED | REAL | Butkhuzi-owned, temporary-hosted-in-svc-tenders | Owns /butkhuzi/norms, /suggest, /search, /upsert, /chunks/rebuild | | Route support boundary | services/svc-tenders/src/routes/support/butkhuziRouteSupport.ts | VERIFIED | REAL | temporary-hosted-in-svc-tenders | Narrow route-facing shell adapter; still built from shared parser/auth helpers | | Persistence repository | services/svc-tenders/src/butkhuzi/repository.ts | VERIFIED | REAL | Butkhuzi-owned, temporary-hosted-in-svc-tenders | Dedicated repository already file-split from root repository | | Domain contracts/types | services/svc-tenders/src/butkhuzi/contracts.ts | VERIFIED | REAL | Butkhuzi-owned | Sprint 75 hardened this out of the mixed root repository | | Norm list/suggest/search flow | services/svc-tenders/src/routes/registerButkhuziRoutes.ts, services/svc-tenders/src/butkhuzi/repository.ts | VERIFIED | REAL | Butkhuzi-owned | Direct DB-backed reads | | Norm upsert flow | same files plus services/svc-tenders/src/validation.ts | VERIFIED | REAL | Butkhuzi-owned with shared validation residue | Auth-protected write path | | Chunk rebuild flow | same files plus migrations for butkhuzi_chunks | VERIFIED | REAL | Butkhuzi-owned | Synchronous admin rebuild action, not background job |

Shared dependencies

| Dependency | Current location | Confidence | State | Ownership | Why shared | | --- | --- | --- | --- | --- | --- | | Gateway seam | services/api/src/routes/butkhuzi.ts | VERIFIED | REAL | shared-Kvary-owned | Public API façade and env seam should remain shared initially | | Gateway auth gate | services/api/src/routes/butkhuzi.ts, services/api/src/auth/middleware.ts | VERIFIED | REAL | shared-Kvary-owned | Protects admin write endpoints before proxying | | Service auth / principal ingress | services/svc-tenders/src/server.ts shell helpers | VERIFIED | REAL | shared-Kvary-owned | requireServiceAuth is still part of the service shell, not Butkhuzi-only logic | | Validation schemas | services/svc-tenders/src/validation.ts | VERIFIED | MIXED | shared-Kvary-owned for now | Butkhuzi schemas still live in the mixed validation file | | Web portal API wrapper | apps/web/src/portal/api.ts | VERIFIED | REAL | shared-Kvary-owned client seam | KES/admin pages consume Butkhuzi through the portal client |

Temporary hosting points

| Hosting point | Current location | Confidence | State | Ownership | Notes | | --- | --- | --- | --- | --- | --- | | Runtime host | services/svc-tenders/src/server.ts | VERIFIED | REAL | temporary-hosted-in-svc-tenders | Butkhuzi routes are mounted directly in the svc-tenders runtime | | Root repository compatibility delegation | services/svc-tenders/src/repository.ts | VERIFIED | MIXED | temporary-hosted-in-svc-tenders | Delegates to ButkhuziRepository; no longer canonical owner | | Migrations | services/svc-tenders/migrations/0009_butkhuzi_norms.sql, services/svc-tenders/migrations/0010_butkhuzi_norms_blocks.sql, services/svc-tenders/migrations/0011_butkhuzi_norms_i18n.sql, services/svc-tenders/migrations/0012_butkhuzi_chunks.sql | VERIFIED | REAL | temporary-hosted-in-svc-tenders | Still canonical schema location today |

UI / client reality

| Surface | Current location | Confidence | State | Ownership | Notes | | --- | --- | --- | --- | --- | --- | | Portal client types and fetchers | apps/web/src/portal/api.ts | VERIFIED | REAL | shared-Kvary-owned | Owns duplicated Butkhuzi response/input types plus fetch helpers | | KES page usage | apps/web/src/app/[locale]/(portal)/kes/page.tsx, apps/web/src/app/[locale]/[country]/(portal)/kes/page.tsx | VERIFIED | MIXED | shared-Kvary-owned consumer | Strongest current product consumer is KES UI, not a standalone Butkhuzi app |

What is missing or still mixed

| Surface | Current location | Confidence | State | Ownership | Notes | | --- | --- | --- | --- | --- | --- | | Domain-owned validation module | missing; schemas still in services/svc-tenders/src/validation.ts | VERIFIED | MIXED | ambiguous | Extraction should move these into a Butkhuzi-owned file | | Standalone runtime/bootstrap | not present | VERIFIED | MISSING | Butkhuzi-owned future target | No extracted svc-butkhuzi runtime yet | | Dedicated web/frontend boundary | not present | VERIFIED | MISSING | ambiguous | Current usage is embedded in KES/admin UI | | Event/Kafka contract | none found | VERIFIED | MISSING | n/a | No real Kafka dependency for Butkhuzi today |

Minimum credible Butkhuzi extraction package

The smallest credible Butkhuzi extraction package today is:

• services/svc-tenders/src/butkhuzi/contracts.ts
• services/svc-tenders/src/butkhuzi/repository.ts
• services/svc-tenders/src/routes/registerButkhuziRoutes.ts
• services/svc-tenders/src/routes/support/butkhuziRouteSupport.ts
• Butkhuzi validation schemas currently inside services/svc-tenders/src/validation.ts
• Butkhuzi migrations 0009 through 0012

Shared shell expected to remain outside that package initially:

• services/api/src/routes/butkhuzi.ts
• gateway auth middleware
• shared auth/principal resolution semantics

Top blockers

| Blocker | Severity | Type | Why it blocks extraction | How to reduce it | | --- | --- | --- | --- | --- | | Validation schemas still live in mixed root validation file | MEDIUM | code-only | Prevents a clean domain-owned package | Move Butkhuzi schemas into a local validation module | | Route and repository types still duplicated in web portal client | MEDIUM | code-only | Makes contract ownership less explicit across service/client boundary | Decide whether to share generated/shared contracts or keep portal-local copies intentionally | | Runtime still hosted only in svc-tenders | MEDIUM | code+infra | No extracted bootstrap exists yet | Copy-first runtime/bootstrap creation later | | Migrations still owned by svc-tenders | MEDIUM | code+infra | Canonical schema ownership has not moved | Settle migration ownership when runtime extraction starts | | KES/admin-adjacent product consumption | LOW | docs-only / product-shape | Product usage still reads as embedded capability rather than standalone platform | Keep shared-shell contract explicit; do not fake independent product boundary |

Recommended extraction direction

Recommended next direction:

1. Butkhuzi code-boundary hardening first
2. Butkhuzi validation and contract ownership cleanup second
3. Butkhuzi runtime/bootstrap prep after that

Why:

• gateway seam already exists
• persistence is already split to a dedicated repository file
• data model is already distinct
• the remaining blockers are mainly shell/validation/runtime ownership rather than domain ambiguity