Loading module
Resolving locale, route permissions, and workspace projection.
Kvary.Network Full System Audit Context
Date: 2026-03-16
Audit mode: repository inspection
Scope: frontend, backend, data layer, services, mock/fallback paths, integration status
UNREAD
PUBLIC | DRAFT | v1.0.0
UNREAD
GOVERNANCE FORMS AUTOFILL STATE DISCOVERY.Ka
PUBLIC | DRAFT | v1.0.0
UNREAD
EX TN 01 UI TRANSLATION SPEC
PUBLIC | DRAFT | v1.0.0
UNREAD
UNREAD
Audit framing
This document is meant to brief a fresh AI session or architect on the real state of the repo.
It is intentionally blunt about the difference between:
- real end-to-end implementation
- mixed real plus fallback behavior
- UI-first prototype behavior
- missing backend or operational pieces
This audit is based on source inspection, not a full runtime verification of every route.
Legend
REAL: code shows concrete backend persistence and service logicMIXED: real backend exists, but UI or gateway can fall back to fixtures, local engines, or catalogsUI-FIRST: polished UI exists, but core action flow is still client/session/local/mockSHELL: visible page exists, but it is mainly structural or placeholderMISSING: not meaningfully implemented yet
1. Architecture Overview
Frontend
- Main frontend is
apps/web using Next.js App Router, React, and TypeScript.
- The portal surface is broad and includes:
- auctions
- tenders
- vacancies
- accommodations
- logistics and equipment
- KES
- ICPI
- map
- stakeholder onboarding
- landowner onboarding
- owner and employer workspaces
- docs and AI assistant surfaces
- Frontend architecture is richer than the backend architecture documentation suggests.
- UI quality is high in many areas, but several domains use fallback/mock data paths that can make the system look more complete than it is.
Backend
- Actual gateway layer is
services/api, not services/gateway.
services/api is not a pure gateway. It is a mixed facade:
- proxying to real services
- exposing local fixture-backed routes
- preserving legacy local engines for auctions and tenders
- The most important operational backend today is
services/svc-tenders.
svc-tenders is effectively a domain monolith for:
- auctions
- tenders
- vacancies
- accommodations
- ICPI
- Butkhuzi
- KES orchestrator
- declaration workflows
- output allocations
- Other real services exist:
services/svc-authservices/svc-riskservices/svc-kycservices/svc-carbon
- There is also a separate
packages/identity-infra backend-like package with migrations and server code, which creates overlap with svc-auth.
Shared domain and core packages
packages/core is the cleanest and most credible layer in the repo.- It contains deterministic domain logic for:
- auctions
- tenders
- governance
- KES
- ledger
- immutability
- settlement
- policy
packages/tender-domain provides shared tender and instrument types, but repo hygiene is weaker there because compiled .js files are committed beside .ts.
Data and infrastructure
- Postgres is real and central.
- Kafka is real for KES/event flows.
- MinIO is prepared and referenced for evidence storage.
- AI memory uses Postgres.
- Carbon uses Postgres.
- Identity/auth uses Postgres.
- Tender/auction/vacancy/accommodation state uses Postgres in
svc-tenders.
Reality check
- The codebase is not yet a clean microservice system.
- It is closer to:
- one Next.js app
- one mixed gateway/facade
- one large operational service
- several real side services
- several fallback/mock paths
- a strong deterministic core
- experimental or future-facing financial/web3 layers
ARCHITECTURE.md is partly outdated versus the actual repo.
- It references
services/gateway, while the real code uses services/api.
- It mentions
packages/sdk, which is not part of the actual current repo structure.
2. Feature Map
| Feature | Status | Honest assessment |
| --- | --- | --- |
| Authentication and sessions | REAL | svc-auth is substantial: signup, register, login, refresh, logout, sessions, profile, 2FA, avatar upload, Google OIDC hooks |
| Stakeholder identity and onboarding | REAL to MIXED | identity-infra has real migrations and repositories; portal onboarding exists; gateway proxies stakeholder-context; architecture overlap with auth is still unresolved |
| Stakeholder context and role-based access | REAL | Gateway auth middleware and policy guards exist; stakeholder context route proxies real upstream service |
| Auctions public portal | MIXED | Rich UI exists and svc-tenders has real auction read/write logic, but gateway local engine and web mock fallback still exist |
| Auctions bid flow | UI-FIRST to MIXED | Detail UI is advanced, but much of the live action behavior added recently is still session-local or overlay-based rather than fully persisted through a dedicated auction mutation path |
| Auction declarations and RWA instruments | REAL to MIXED | Shared types, validation, repository mapping, and detail rendering exist; declaration/admin path is real in svc-tenders; some user-side action surfaces are still local-state heavy |
| Auction settlement entitlement semantics | REAL | entitlementId is generated and stored in svc-tenders settlement path |
| Tender public portal | MIXED | Real backend exists in svc-tenders, but gateway still preserves legacy local engine routes and web fallback mocks |
| Tender declaration/admin review flow | REAL | Submission, queue, approve, reject paths exist and use auth/policy gates |
| Vacancies public catalog | MIXED | svc-tenders has real vacancy domain/read model/command handlers, but web can fall back to static catalog data |
| Vacancy applications and employer workspace | REAL to MIXED | Backend paths exist and owner/employer UI is real, but fallback catalog logic still exists on read side |
| Accommodations public catalog | MIXED | svc-tenders has real domain/read model/quote/booking paths, but web has fallback accommodation catalog data |
| Accommodation bookings and owner workspace | REAL to MIXED | Real backend commands exist; UI is extensive; fallback data still exists for catalog resilience |
| Logistics & Equipment workspace | UI-FIRST | Strong UI and operational framing exist, but request creation, selection, and queue behavior are largely session-backed, not persisted in a transport backend |
| Auction-linked transport handoff | UI-FIRST to MIXED | Hand-off semantics are wired into auction UI and transport workspace, but operational fulfillment state is mostly session-local |
| Winner fulfillment flow | UI-FIRST | User-facing flow exists, but selection state is session-local and there is no durable fulfillment/order backend |
| Map and geospatial portal | MIXED to SHELL | MapLibre UI is real and interactive, but API map overview is built from fixture/visibility logic; parcel registry page is explicitly a shell |
| Parcels | SHELL | Page explicitly states parcel operations are routed through map projection and is read-only structural shell |
| KES main workspace | MIXED | Very substantial UI exists; some backend integrations are real; much of the workspace is client-heavy and not clearly a full multi-user persisted operational product yet |
| KES orchestrator | REAL to MIXED | svc-tenders exposes real KES orchestrator routes and Kafka/event tooling exists; frontend is advanced; some flows may still be operator-oriented rather than hardened product workflow |
| ICPI pricing | REAL | Real endpoints in svc-tenders; portal pages exist |
| Butkhuzi norms | REAL | Real endpoints in svc-tenders; portal/KES tooling integrates with it |
| Carbon project lifecycle | REAL backend, weak portal presence | svc-carbon has real CRUD/lifecycle/audit logic; clear portal product layer is not yet obvious |
| AI docs assistant / founder AI context | MIXED | Real Next API routes, real memory layer, real RAG bootstrap, but embeddings can silently fall back to deterministic stub mode if no OpenAI key is configured |
| Web3 / wallet / token issuance | MISSING as product flow | Financial-layer code and scripts exist, but user-facing wallet and tokenized asset runtime are not productized |
| Secondary market / DeFi | MISSING | No real product flow |
| Logistics dispatch engine | MISSING | Current logistics is workspace/UI, not dispatch orchestration |
3. Data Layer
What is real
- Postgres-backed services with migrations exist for:
services/svc-auth/migrationsservices/svc-carbon/migrationsservices/svc-kyc/migrationsservices/svc-risk/migrationsservices/svc-tenders/migrationspackages/identity-infra/migrationspackages/memory-layer/migrations
svc-tenders repository is large and central. It stores auctions, tenders, vacancies, accommodations, KES orchestrator state, and related projections.memory-layer persists founder AI chat sessions/messages in Postgres and attempts vector extension setup.svc-carbon has real repository and audit tables for project lifecycle, MRV, verification, issuance, retirement.svc-auth has real account/session/profile storage.identity-infra has real identity, RBAC request, stakeholder application, and landowner onboarding tables.
What is mock or fallback
- Web portal fallback mocks:
apps/web/src/lib/mock/portalMock.ts- tender and auction summary/detail fallbacks
- Web fallback static catalogs:
- Gateway local engines and legacy fallback logic:
services/api/src/routes/auctions.tsservices/api/src/routes/tenders.ts
- Map overview route is not reading a real parcel registry backend; it uses fixture-driven visibility logic.
What is missing
- No unified persistent logistics request or fulfillment store yet.
- No durable auction bidder-side transport selection persistence.
- No durable winner fulfillment orchestration store.
- No productized parcel registry backend visible from the current portal.
- No clearly unified canonical data contract across gateway, services, and web fallbacks.
Important data-flow truth
- There are several places where the UI can still show a coherent experience even when the underlying service is unavailable, because the code falls back to:
- local mock data
- local engines
- static catalogs
- This is useful for demo resilience, but dangerous for founder-level situational awareness because it blurs real uptime and real capability.
4. API Layer
Gateway
services/api/src/server.ts exposes the main public API surface.- Major route families include:
- auth
- profile
- stakeholder-context
- stakeholder-applications
- map
- tenders
- auctions
- vacancies
- accommodations
- vacancy and accommodation owner flows
- risk
- ICPI
- Butkhuzi
- KES orchestrator
Endpoint status by pattern
REAL-PROXY
- auth routes mostly proxy to
svc-auth
- stakeholder-context proxies upstream
- vacancies and accommodations proxy to
svc-tenders
- risk proxies/relays real service behavior
MIXED-PROXY-FALLBACK
- auctions route can proxy upstream, but can also fall back to gateway-local engine
- tenders route proxies real backend, but still contains legacy engine and outbox behavior
FIXTURE-DRIVEN
- map overview currently uses fixture/visibility builder
API truth by domain
- Auth API is one of the strongest real pieces.
- Tender and auction APIs are the most mixed and architecturally confusing because:
- real service exists
- gateway local engines still exist
- web fallback mocks still exist
- Vacancies and accommodations are more real than auctions from a backend perspective, but the portal still has fallback catalogs.
- KES, ICPI, and Butkhuzi have real service endpoints, but frontend persistence and product hardening vary by subfeature.
5. State of Integrations
Blockchain / Web3
- Status: PARTIAL / EXPERIMENTAL
- Evidence:
packages/financial-layer- chain anchoring helpers
- Algorand-related scripts and dry-run tooling
- Honest state:
- there is meaningful technical groundwork
- there is not a production user-facing wallet or token flow
- no real secondary-market product path exists
- no end-user on-chain lifecycle is integrated into auctions/tenders today
Wallet systems
- Status: MISSING as product capability
- No clear end-user wallet connection and signing flow is implemented as a live platform capability.
Mapping / geospatial
- Status: PARTIAL
- Frontend MapLibre-based map is real and interactive.
- Backend map data source is still lightweight and fixture/projection driven.
- Parcels are not a real standalone registry product yet.
AI services
- Status: MIXED
- Real pieces:
- AI API routes in Next.js
@kvary/ai-layer@kvary/memory-layer- docs RAG bootstrap
- Constraint:
- if OpenAI key is not configured, embedding provider can fall back to deterministic stub mode
- Meaning:
- AI UX exists
- some behavior may be authentic application logic
- some model/runtime quality may silently degrade in non-key environments
Kafka / event-driven system
- Status: REAL
- Strong evidence:
- KES event consumers
- outbox relay
- idempotency store
- DLQ replay tooling
- Kafka smoke audit docs
- This is one of the strongest backend architectural signals in the repo.
KYC
- Status: REAL service, product integration still partial
svc-kyc exposes:
- session creation
- provider webhook
- self read endpoint
- Product orchestration is still not a full end-user compliance product.
6. Technical Debt and Architectural Risks
1. Gateway reality drift
services/api is both:
- gateway
- fallback engine
- fixture provider
- This makes operational truth harder to see.
- It also makes debugging harder because identical UI paths can be backed by different sources depending on environment and failure mode.
2. Mock and fallback paths can create product illusion
- Web portal uses:
- portal mocks
- static catalogs
- safe fallbacks
- Gateway uses:
- local auction engine
- legacy tender engine
- This is useful for demos, but risky for decision-making because polished UI can appear live while backend capability is absent.
3. svc-tenders is becoming a monolith
- It owns too many domains:
- tenders
- auctions
- vacancies
- accommodations
- ICPI
- Butkhuzi
- KES orchestrator
- declarations
- This is probably acceptable short term, but it is the main scaling and maintainability risk.
4. Identity/auth split is confusing
svc-auth is a real auth service.packages/identity-infra also behaves like a service and owns identity/RBAC/stakeholder persistence concerns.- The long-term service boundary is not clean.
5. Documentation drift
- Architecture docs do not match actual repo shape in some important places.
- This is dangerous in an AI-assisted codebase because AI tools will internalize wrong topology.
6. Compiled JavaScript committed in source
- There are committed
.js files beside .ts files in multiple service/package source folders.
- This increases drift risk and audit noise.
7. Test coverage is uneven
packages/core is relatively well tested.svc-tenders has some tests in vacancy/accommodation modules.- Broader integration tests are thin.
- Frontend behavior-heavy areas are not convincingly protected by tests.
8. Session-local business behavior is overused in newer UX
- Auction bid overlays
- transport selection
- winner fulfillment
- direct transport requests
- equipment requests
- some auction-linked operational flows
These improve UX quickly, but they are not durable business workflows yet.
9. Environment and port drift risk
- Example: web API base URL default and dev scripts do not always align cleanly.
- This increases false-negative and false-positive behavior during local development.
10. Security and production-hardening gaps
- Dev impersonation exists in auth service behind flags.
- There are many routes and broad surfaces, but full audit of authorization consistency is still needed.
- Sensitive operational services should eventually have stronger internal service auth boundaries and observability.
7. Development Roadmap
Short term: next 2 weeks
- Remove ambiguity in system truth.
- Priorities:
- create a single founder-visible capability matrix per domain
- add explicit
source markers in critical UI paths when data comes from mock, local engine, or real service
- decide which auction/tender paths are canonical and disable unused fallbacks in at least one stable environment
- standardize API base URLs and local dev topology
- clean compiled
.js artifacts from source directories
- document exact ownership boundaries between
svc-auth, identity-infra, and svc-tenders
- add health/readiness checks that reflect real upstream availability instead of demo resilience
Mid term: next 2 months
- Turn the strongest domains into clearly real end-to-end products.
- Suggested priority order:
- auth and stakeholder identity consolidation
- auctions and tenders canonical backend path
- vacancies and accommodations hardening
- logistics request persistence and fulfillment persistence
- KES orchestrator operational hardening
- carbon integration into visible portal workflow
- integration tests across web -> API -> service -> DB
Long term architecture goals
- Convert current mixed architecture into explicit layers:
- frontend
- thin API facade
- clearly bounded domain services
- deterministic shared core
- event backbone
- optional financial/web3 adapters
- Eliminate hidden fallback behavior from production paths.
- Make all critical business actions durable and auditable.
- Keep UI polish, but reduce session-local illusions.
8. Critical Missing Components: Top 10
- Canonical production truth path for auctions and tenders
- Right now too many fallback layers exist.
- Durable bid submission and auction action backend path for the modern auction UI
- Current UI is richer than the underlying persisted action model.
- Real logistics request and fulfillment persistence
- Current logistics and winner fulfillment are still mostly workspace/session behavior.
- Unified identity/stakeholder architecture
svc-auth and identity-infra boundaries need simplification.
- Parcel registry and real geospatial domain backend
- Current map is useful, but parcel domain is not yet a full product.
- Strong integration and end-to-end test coverage
- Especially across proxy/fallback-heavy domains.
- Production observability and explicit source transparency
- Need clear runtime indication of mock vs real vs degraded data source.
- Carbon portal productization
- Backend exists, but visible product integration is weak.
- Productized Web3/wallet/issuance strategy
- Financial layer exists as groundwork, but not as a platform capability.
- Domain decomposition plan for
svc-tenders
- It is carrying too much platform weight.
9. Domain-by-domain bottom line
Strongest real domains today
- Auth and profile
- Deterministic core domain logic
svc-tenders persistence layer- KES event infrastructure
- ICPI and Butkhuzi service endpoints
- Carbon backend
Strongest UI but least durable action flows
- Modern auction detail and RWA instrument experience
- Logistics & Equipment workspace
- winner fulfillment continuation
Most likely to mislead a new AI session if not explained
- Auctions
- Tenders
- Logistics
- Map/parcels
- AI runtime quality
- all of these have some combination of polished UI, local fallback, or session-local state that can look like a finished backend product.
10. Recommended handoff summary for a fresh GPT session
- Kvary.Network is already a serious multi-domain platform repo, not a toy frontend.
- The cleanest real layer is
packages/core.
- The most real operational backend is
services/svc-tenders.
- The most real user/account backend is
services/svc-auth.
- The architecture is not yet cleanly decomposed; gateway, local engines, mocks, and real services coexist.
- Auctions, tenders, logistics, and some portal experiences are currently the highest risk for “UI looks real but action path is not fully canonical”.
- Carbon, KYC, risk, and AI all exist in meaningful code, but portal-level productization varies.
- Web3 is still groundwork, not live product capability.
11. File paths that matter most for future audits
apps/web/src/portal/api.tsapps/web/src/lib/mock/portalMock.tsservices/api/src/server.tsservices/api/src/routes/auctions.tsservices/api/src/routes/tenders.tsservices/api/src/routes/vacancies.tsservices/api/src/routes/accommodations.tsservices/api/src/routes/map.tsservices/svc-tenders/src/server.tsservices/svc-tenders/src/repository.tsservices/svc-auth/src/server.tsservices/svc-risk/src/server.tsservices/svc-kyc/src/server.tsservices/svc-carbon/src/server.tspackages/corepackages/identity-infrapackages/memory-layerpackages/ai-layerpackages/financial-layer
12. Final honest assessment
Kvary.Network already has more real system substance than a normal AI-generated prototype.
But it also has a major early-stage AI-built risk:
- polished surfaces are ahead of canonical backend truth in several key domains
- fallback logic hides backend gaps
- architecture docs lag reality
- too much platform responsibility is concentrated in a few places
The next phase should not be about adding more surface area first.
- collapsing ambiguity
- making source-of-truth explicit
- turning mixed domains into clean end-to-end domains
- and preventing UI polish from outpacing durable business state