Butkhuzi API And Persistence Surface

Route and API surface

Current public gateway surface:

• services/api/src/routes/butkhuzi.ts

Current route set:

• GET /butkhuzi/norms
• GET /butkhuzi/suggest
• GET /butkhuzi/search
• POST /butkhuzi/upsert
• POST /butkhuzi/chunks/rebuild

Current runtime host:

• services/svc-tenders/src/routes/registerButkhuziRoutes.ts

Surface classification

| Route surface | Classification | Notes | | --- | --- | --- | | GET /butkhuzi/norms | stable route surface | Real DB-backed list with filters and pagination | | GET /butkhuzi/suggest | stable route surface | Real suggest flow against Butkhuzi norms | | GET /butkhuzi/search | stable route surface | Real chunk-backed full-text search | | POST /butkhuzi/upsert | stable route surface | Auth-protected admin ingest/update path | | POST /butkhuzi/chunks/rebuild | transitional route surface | Real behavior, but still a synchronous admin action and future runtime concern |

API extraction notes

• VERIFIED: API gateway already supports extraction through BUTKHUZI_SERVICE_URL ?? TENDERS_SERVICE_URL.
• VERIFIED: route shape already looks service-friendly; there is no local fallback engine in services/api.
• VERIFIED: auth remains shared at both gateway and service-shell levels.

Persistence surface

Current canonical Butkhuzi tables:

• 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

Current repository owner:

• services/svc-tenders/src/butkhuzi/repository.ts

Persistence classification

| Data surface | Classification | Notes | | --- | --- | --- | | butkhuzi_norms | stable persistence surface | Canonical norms store | | butkhuzi_chunks | stable persistence surface | Canonical search substrate, tied to norms | | root delegation in services/svc-tenders/src/repository.ts | mixed / temporary | Transitional compatibility delegation only |

Persistence extraction notes

• VERIFIED: Butkhuzi data is already isolated enough for a later copy-first service runtime.
• VERIFIED: migration ownership is still inside svc-tenders.
• VERIFIED: there is no evidence of cross-domain Butkhuzi tables outside the Butkhuzi table family.

Contracts and validation surface

Current Butkhuzi-owned contracts:

• services/svc-tenders/src/butkhuzi/contracts.ts

Current validation location:

• services/svc-tenders/src/validation.ts

Classification

| Surface | Classification | Notes | | --- | --- | --- | | Butkhuzi route/persistence contracts | stable but transitional location | Domain-owned file now exists | | Butkhuzi validation schemas | mixed | Still live in shared validation file | | portal client types in apps/web/src/portal/api.ts | transitional / duplicated | Client copies of backend shapes still exist |

Runtime assumptions

| Runtime assumption | Classification | Notes | | --- | --- | --- | | Hosted in svc-tenders | temporary | Current truth, not target ownership | | Shared auth ingress | shared on purpose | Suitable to keep shared during first extraction | | Gateway env seam | stable | Good extraction seam already exists | | Kafka/event dependency | absent | No real Kafka dependency found for Butkhuzi |

Extraction notes

The code truth supports a Butkhuzi extraction path that is:

• package-first
• then runtime/bootstrap-first
• with API seam already ready

The main cleanup before actual extraction is not domain ambiguity. It is remaining shared-shell residue:

• validation schemas
• root compatibility delegation
• migration ownership still in svc-tenders
• duplicated portal client contracts