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.

It keeps these distinctions explicit:

• accommodation route/API surface
• vacancy / worker route/API surface
• booking / reservation surface
• persistence / read-model surface
• compatibility residue

1. Accommodation route / API surface

| 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. |

2. Vacancy / workforce route / API surface

| 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. |

3. Booking / reservation / application surface

| 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. |

4. Persistence / read-model surface

Accommodation persistence

| 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. |

Vacancy persistence

| 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. |

Shared / mixed persistence pieces

| 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. |

5. Compatibility residue notes

The most important compatibility residue still present is:

1. vacancy public fallback to legacy vacancies
2. accommodation compatibility reads through root repository / legacy accommodations
3. frontend fallback catalogs:
   • apps/web/src/features/domains/vacancyCatalog.ts
   • apps/web/src/features/domains/accommodationCatalog.ts
4. frontend workforce and map datasets backed by mock data rather than backend APIs

These should not be mistaken for a unified extracted WorkStay backend.

6. Extraction notes

Most extraction-ready surfaces

• vacancy posting and application mutations
• owner vacancy reads
• accommodation listing / booking mutations at the service level
• accommodation owner reservation reads
• accommodation public list/detail/quote service logic

Most problematic surfaces

• public vacancy discovery due to active legacy fallback
• accommodation gateway mutation/read paths that still target only TENDERS_SERVICE_URL
• workforce / nearby intelligence / map surfaces because they are frontend mock or catalog composition today

Safest near-term direction

1. harden vacancy and accommodation contracts separately
2. complete accommodation gateway seam parity with vacancy
3. reduce root compatibility hosting
4. only then decide whether a single combined WorkStay runtime is ready