Accommodation Shared Shell Contract

Purpose

This document defines the minimum shared shell that accommodation should still rely on after extraction.

It keeps current gateway and auth behavior explicit instead of pretending accommodation will become fully isolated in one step.

1. Gateway behavior

Current gateway seam:

• ACCOMMODATIONS_SERVICE_URL ?? TENDERS_SERVICE_URL ?? "http://localhost:4020"

Gateway owner remains:

• services/api/src/routes/accommodationsServiceTarget.ts
• services/api/src/routes/accommodations.ts
• services/api/src/routes/accommodation-listings.ts
• services/api/src/routes/accommodation-bookings.ts
• services/api/src/routes/my-accommodation-bookings.ts
• services/api/src/routes/owner-accommodation-listings.ts
• services/api/src/routes/owner-accommodation-reservations.ts

Verdict:

• must remain shared

Reason:

• the API gateway is the stable external façade and rollback seam
• accommodation extraction should happen behind it, not by changing public route shape

2. Auth behavior

Current service-side auth ingress behavior:

• bearer token required on protected write/owner routes
• token verified with shared JWT_SECRET
• principal resolved upstream through /auth/me
• inactive principals denied after resolution

Current shared dependency:

• shared auth/identity service contract behind /auth/me

Verdict:

• service-side auth ingress contract must remain shared
• implementation can be copied into accommodation runtime later

Reason:

• auth semantics must stay identical during copy-first extraction
• this is shared Kvary backbone behavior, not accommodation domain logic

3. Shared auth/identity expectations

Accommodation runtime should continue to expect:

• JWT_SECRET
• AUTH_SERVICE_URL
• /auth/me returning the same principal shape currently parsed by service runtimes

Verdict:

• must remain shared

Later option:

• runtime-local auth adapter can be wrapped behind a narrower accommodation shell module, but the upstream contract should stay the same during first extraction execution

4. Shared parser/helper expectations

Accommodation route support still depends on:

• requireServiceAuth
• requireActivePrincipal
• parsePositiveInt

Current helper location:

• shell-local helpers in services/svc-tenders/src/server.ts

Verdict:

• can be wrapped later

Reason:

• these helpers are small enough to copy into an accommodation runtime shell once the runtime is created
• they do not need to stay in svc-tenders, but they should not be refactored broadly this sprint

5. Shared upload/storage expectations

No accommodation-specific upload/storage dependency was verified in the inspected accommodation route surface.

Verdict:

• no shared upload/storage contract is currently required for first accommodation extraction prep

6. Env / service target assumptions

Current target env contract:

• ACCOMMODATIONS_SERVICE_URL optional
• falls back to TENDERS_SERVICE_URL

Verdict:

• must remain shared

Reason:

• this is the rollback-safe gateway seam for future copy-first runtime cutover

7. What remains shared on purpose

• API gateway façade
• shared auth/identity resolution contract
• shared bearer/JWT ingress contract
• rollback via ACCOMMODATIONS_SERVICE_URL fallback

8. What should move into accommodation later

• route registration
• route support implementation
• accommodation read/write repositories
• accommodation quote logic
• accommodation domain + validation modules

9. What remains unresolved

• whether detailExtractionSupport.ts should be duplicated locally or moved to a narrower shared helper home
• when mixed accommodation migrations stop living under svc-tenders
• when root compatibility hosting in services/svc-tenders/src/repository.ts can be retired