Butkhuzi Extraction Prep Map
This document defines the current Butkhuzi extraction boundary from code truth.
It does not assume a standalone runtime already exists.
Loading module
Resolving locale, route permissions, and workspace projection.
Resolving locale, route permissions, and workspace projection.
Current scope: Guest
Category: 10_normative | Version: v1.0.0
Owner: DOCUMENT_CUSTODIAN | Review cycle: 90 days
Approval authority: GOVERNANCE_ADMIN
Documentation portal is read-only. Editing and mutation endpoints are disabled.
Kvary platform is originally created in Georgian. Where a Georgian version exists, Georgian is authoritative for platform UI, documentation, and legal interpretation.
Translations into other languages are provided for convenience. Some records may originate in other languages and carry their own source or legal locale for a specific flow, but where a Georgian version is available, the Georgian version prevails for platform-level wording and interpretation.
Metadata incomplete: Document ID, Version, Status, Owner Role, Last Review Date, Next Review Date, Change Log
This document defines the current Butkhuzi extraction boundary from code truth.
It does not assume a standalone runtime already exists.
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.| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
The smallest credible Butkhuzi extraction package today is:
0009 through 0012Shared shell expected to remain outside that package initially:
| 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 next direction:
Why: