Current Architecture

Status: ACTIVE
Audit Date: 2026-03-16
Audit Basis: code-verified repository inspection

Executive Truth

• VERIFIED: Kvary.Network is currently a hybrid system, not a clean microservice platform.
• VERIFIED: The strongest real backend shape is a mixed topology of:
  • apps/web as the primary UI
  • services/api as public façade/gateway plus local fallback engines
  • services/svc-tenders as the largest remaining operational domain service plus shared KES event backbone host
  • services/svc-kes as the canonical extracted KES HTTP/runtime host
  • services/svc-auth, services/svc-risk, services/svc-kyc, services/svc-carbon as real side services
  • packages/identity-infra as a second backend-style identity/stakeholder runtime with overlapping responsibility
• VERIFIED: Kafka/event-driven architecture is real, but concentrated mainly in KES + outbox + projection flows inside svc-tenders.
• VERIFIED: Several user-facing flows still rely on mock data, fixture engines, or sessionStorage, especially in auctions and logistics/equipment.
• VERIFIED: services/api is not only a gateway. It is a façade, proxy layer, fallback engine, and legacy compatibility surface.

Runtime Topology

apps/web

• Purpose: Next.js App Router UI, portal pages, docs/AI route handlers, internal admin fetch routes.
• Evidence:
  • apps/web/src/app does page composition.
  • apps/web/src/portal/api.ts performs direct REST fetches and fallback handling.
  • apps/web/src/app/api/ai/ask/route.ts runs server-side AI route logic.
• State: MIXED
• Notes:
  • Reads real APIs.
  • Uses mock/fallback builders for some domains.
  • Uses sessionStorage for several auction/logistics UX flows.

services/api

• Purpose: Public API surface for the web app.
• Evidence:
  • services/api/src/server.ts mounts all public routers.
  • Routers proxy to other services, but some domains have local fallback engines.
• State: MIXED
• Reality:
  • VERIFIED: Acts as a gateway/facade for auth, risk, stakeholder, tenders, and KES.
  • VERIFIED: Also contains local engines for auctions and legacy tenders.
  • VERIFIED: Also contains fixture/projection routes such as map.
• Answer:
  • services/api is all of the above: gateway, façade, fallback engine, and compatibility layer.

services/svc-tenders

• Purpose: Tender/auction/declaration service plus shared KES event-backbone workers.
• Evidence:
  • services/svc-tenders/src/server.ts
  • services/svc-tenders/src/repository.ts
  • services/svc-tenders/src/kafka
• State: REAL
• Reality:
  • VERIFIED: Owns durable Postgres-backed flows for tenders.
  • VERIFIED: Retains the shared KES Kafka/outbox/projection/idempotency/DLQ backbone.
  • VERIFIED: The old colocated KES HTTP host is retired.
  • VERIFIED: Extracted HTTP/runtime hosts now front KES, ICPI, Vacancy, Accommodation, and Butkhuzi.
• Answer:
  • svc-tenders is becoming a domain monolith.

services/svc-kes

• Purpose: canonical KES HTTP/runtime host.
• Evidence:
  • services/svc-kes/src/server.ts
  • services/svc-kes/src/kes/repository.ts
• State: REAL
• Reality:
  • VERIFIED: Owns the extracted KES route/support/runtime surface.
  • VERIFIED: Owns canonical KES SQL, row mapping, payment-note handling, and kes_orchestrator_events persistence.
  • VERIFIED: Still depends on shared auth /auth/me resolution and the shared KES event backbone that remains in svc-tenders/src/kafka.

services/svc-auth

• Purpose: canonical auth/session/account backend.
• Evidence:
  • services/svc-auth/src/server.ts
• State: REAL
• Capabilities:
  • register/signup/login/logout/refresh
  • sessions listing/revocation
  • 2FA TOTP
  • email verification
  • Google OIDC
  • profile/admin user flows

services/svc-risk

• Purpose: risk scoring / risk API service.
• Evidence:
  • services/svc-risk/src
• State: REAL
• Notes:
  • Real service boundary exists, but not all product surfaces were traced end-to-end in this audit.

services/svc-kyc

• Purpose: KYC/compliance service.
• Evidence:
  • services/svc-kyc/src
• State: REAL
• Notes:
  • Real runtime exists; web integration appears partial in current UX.

services/svc-carbon

• Purpose: carbon project lifecycle backend.
• Evidence:
  • services/svc-carbon/src/server.ts
• State: REAL

packages/identity-infra

• Purpose: second backend-style runtime for auth + stakeholder onboarding + review workflows.
• Evidence:
  • packages/identity-infra/src/server.ts
• State: MIXED
• Reality:
  • VERIFIED: Contains real endpoints and persistence-backed stakeholder flows.
  • VERIFIED: Overlaps with svc-auth and gateway stakeholder routes.
• Boundary risk:
  • Gateway does not expose all reviewer endpoints even though this package implements them.

packages/core

• Purpose: shared domain contracts and common types.
• Evidence:
  • packages/core
• State: REAL
• Notes:
  • One of the cleanest repo layers.

packages/tender-domain

• Purpose: tender/auction declarations, domain types, helpers.
• Evidence:
  • packages/tender-domain
• State: REAL

packages/financial-layer

• Purpose: future-oriented chain/mint/orchestration package with Kafka DTOs and scripts.
• Evidence:
  • packages/financial-layer/chain/orchestration
• State: MIXED
• Reality:
  • VERIFIED: Kafka DTOs and adapters exist.
  • VERIFIED: active usage is mostly script/demo/operator tooling, not core app runtime.

Memory / AI packages

• packages/memory-layer
  • Purpose: AI conversation/session persistence.
  • Evidence: packages/memory-layer/src/repository.ts
  • State: REAL
• apps/web/lib/docsRagBootstrap.ts
  • Purpose: docs RAG bootstrap and embeddings provider setup.
  • State: MIXED
  • VERIFIED: Uses OpenAI when configured, deterministic stub embeddings otherwise.

Cleanest Boundaries

• VERIFIED: shared domain contracts in packages/core
• VERIFIED: tender/KES persistence and event outbox inside services/svc-tenders
• VERIFIED: auth/session flows inside services/svc-auth

Dirtiest Overlaps

• VERIFIED: services/api mixes gateway, local engine, fallback, and compatibility concerns.
• VERIFIED: svc-auth and packages/identity-infra both expose auth-like behavior.
• VERIFIED: auctions are split between:
  • real read/admin declaration logic in svc-tenders
  • local-engine action logic in services/api
  • portal mocks/session-local overlays in apps/web

Public Route Reality Highlights

• VERIFIED: public API routers are mounted in services/api/src/server.ts.
• VERIFIED: svc-tenders owns real routes for:
  • /tenders
  • /tenders/submit
  • /tenders/:id
  • /auctions
  • /auctions/:id
• VERIFIED: there is no real public svc-tenders bid mutation route analogous to the local services/api auction engine POST /auctions/:id/bids.
• VERIFIED: KES now routes through services/api/src/routes/kes-orchestrator.ts to services/svc-kes, not to a colocated svc-tenders KES host.

Architecture Verdict

• System type: HYBRID modular-monolith-plus-services.
• Event-driven maturity: PARTIAL but real.
• Canonical durable backbone today:
  • auth/session in svc-auth
  • tender flows in svc-tenders
  • KES HTTP/runtime in svc-kes
  • shared KES event backbone in svc-tenders/src/kafka
  • selected carbon flows in svc-carbon
• Most misleading assumption to avoid:
  • “The whole platform is already a clean microservice + Kafka system.”
  • That is false. The repo is mixed, and some user-visible flows remain UI-first or fallback-driven.