WorkStay API And Persistence Surface
Purpose
This document maps the current route/API and persistence surfaces that are most relevant to a future WorkStay-style platform.
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 maps the current route/API and persistence surfaces that are most relevant to a future WorkStay-style platform.
It keeps these distinctions explicit:
| Surface | Current module(s) | Classification | Notes |
| --- | --- | --- | --- |
| Public accommodation list/detail/quote | services/svc-tenders/src/routes/registerAccommodationRoutes.ts, services/api/src/routes/accommodations.ts | VERIFIED stable route surface | Backend is real and public gateway seam already exists through ACCOMMODATIONS_SERVICE_URL ?? TENDERS_SERVICE_URL. |
| Owner accommodation listing reads | services/svc-tenders/src/routes/registerAccommodationRoutes.ts, services/api/src/routes/owner-accommodation-listings.ts | VERIFIED stable route surface | Owner reads already have accommodation-specific gateway seam. |
| Owner accommodation reservation reads | services/svc-tenders/src/routes/registerAccommodationRoutes.ts, services/api/src/routes/owner-accommodation-reservations.ts | VERIFIED stable route surface | Reservation reads are real and route-backed. |
| Accommodation listing mutations | services/svc-tenders/src/routes/registerAccommodationRoutes.ts, services/api/src/routes/accommodation-listings.ts | VERIFIED mixed route surface | Backend write path is real, but gateway still targets only TENDERS_SERVICE_URL. |
| Accommodation booking mutations | services/svc-tenders/src/routes/registerAccommodationRoutes.ts, services/api/src/routes/accommodation-bookings.ts | VERIFIED mixed route surface | Durable backend flow exists, but extraction seam is incomplete at the gateway. |
| My accommodation bookings | services/svc-tenders/src/routes/registerAccommodationRoutes.ts, services/api/src/routes/my-accommodation-bookings.ts | VERIFIED mixed route surface | Backend read is real; gateway still points only at TENDERS_SERVICE_URL. |
| Surface | Current module(s) | Classification | Notes |
| --- | --- | --- | --- |
| Public vacancy list/detail | services/svc-tenders/src/routes/registerVacancyRoutes.ts, services/api/src/routes/vacancies.ts | VERIFIED mixed route surface | Route and gateway surface are clean, but public data truth remains mixed because of legacy fallback. |
| Owner vacancy posting reads | services/svc-tenders/src/routes/registerVacancyRoutes.ts, services/api/src/routes/owner-vacancy-postings.ts | VERIFIED stable route surface | Owner vacancy reads already share the vacancy-specific env seam. |
| Vacancy posting mutations | services/svc-tenders/src/routes/registerVacancyRoutes.ts, services/api/src/routes/vacancy-postings.ts | VERIFIED stable route surface | Vacancy mutation gateway seam is already extraction-friendly via VACANCIES_SERVICE_URL ?? TENDERS_SERVICE_URL. |
| Vacancy application reads/mutations | services/svc-tenders/src/routes/registerVacancyRoutes.ts, services/api/src/routes/vacancy-applications.ts, services/api/src/routes/owner-vacancy-applications.ts | VERIFIED stable route surface | This is one of the cleaner future extraction surfaces. |
| Workforce register | apps/web/src/app/[locale]/(portal)/workforce/page.tsx | VERIFIED compatibility / UI-first surface | No matching services/api or svc-tenders backend route was found. |
| Surface | Current truth | Classification | Notes |
| --- | --- | --- | --- |
| Accommodation booking request / owner decision | route-backed + durable | VERIFIED stable backend surface | Strong extraction candidate. |
| Owner accommodation reservations | route-backed + durable | VERIFIED stable backend surface | Uses preferred read model. |
| Vacancy applications | route-backed + durable | VERIFIED stable backend surface | Applicant and owner review surfaces are active. |
| Unified booking + application orchestration | no combined backend surface | VERIFIED MISSING | Future WorkStay intent exists, but current code remains two parallel domain flows. |
| Data surface | Current location | Classification | Notes |
| --- | --- | --- | --- |
| accommodation_listings write table | command handlers + owner reads | VERIFIED REAL | Real listing source of truth. |
| accommodation_bookings write table | command handlers + booking reads | VERIFIED REAL | Real booking source of truth. |
| accommodation_listings_view / accommodation_listing_detail_view | services/svc-tenders/src/accommodation/projections.ts, services/svc-tenders/src/accommodation/readModel.ts | VERIFIED REAL | Preferred public read path. |
| owner reservation views | services/svc-tenders/src/accommodation/projections.ts, services/svc-tenders/src/accommodation/readModel.ts | VERIFIED REAL | Preferred internal/owner reservation reads. |
| legacy accommodations table | compatibility repository | VERIFIED MIXED | Compatibility residue for older root-repository consumers and earlier public discovery paths. |
| Data surface | Current location | Classification | Notes |
| --- | --- | --- | --- |
| vacancy_postings write table | command handlers + owner reads | VERIFIED REAL | Real posting source of truth. |
| vacancy_applications write table | command handlers + application reads | VERIFIED REAL | Real application source of truth. |
| vacancy_postings_view / vacancy_posting_detail_view | services/svc-tenders/src/vacancy/projections.ts, services/svc-tenders/src/vacancy/readRepository.ts | VERIFIED REAL | Preferred modern vacancy read path. |
| my_vacancy_applications_view / vacancy_applications_by_posting_view | same modules | VERIFIED REAL | Preferred application review/read path. |
| legacy vacancies table | preferred read repository fallback | VERIFIED MIXED | Active public discovery still falls back here when projection rows do not exist. |
| Surface | Classification | Notes |
| --- | --- | --- |
| outbox_events used by vacancy/accommodation command handlers | VERIFIED MIXED | Real and local to these domains, but not yet exposed as a clean external event contract. |
| root TendersRepository compatibility hosting | VERIFIED MIXED | Persistence code still exposes vacancy/accommodation compatibility delegation for old callers. |
The most important compatibility residue still present is:
vacanciesaccommodationsThese should not be mistaken for a unified extracted WorkStay backend.
TENDERS_SERVICE_URL