AI_INTEGRATION — bff-tenant-booking-service

Sibling: APPLICATION_LOGIC · SECURITY_MODEL

Cross-cutting: 08 AI Architecture · 03-microservices/ai-orchestrator-service.md

1. Posture

bff-tenant-booking-service makes no direct LLM calls and runs no on-device inference. Every AI capability surfaced on the tenant booking surface is requested from ai-orchestrator-service via REST. The BFF's role is to render the orchestrator's response and to annotate funnel telemetry with AI-influence flags so analytics can attribute AI-driven uplift.

This BFF will never persist AIProvenance directly — that lives on the artifact-owning service (pricing-service for AI-suggested rates, notification-service for AI-drafted abandoned-cart copy, reservation-service for AI-suggested upsell add-ons).

2. AI capabilities surfaced

Capability	Source	Endpoint that triggers / consumes	Render mode	Provenance held by
Smart room recommendation ("guests like you also liked …")	`ai-orchestrator-service` (via `property-service` enrichment)	`GET /availability` (advisory, optional)	inline card with `Recommended` badge	`property-service` (`AIProvenance` on the recommendation row)
AI-drafted special-request acknowledgement	`ai-orchestrator-service`	`PATCH /draft/{id}` (server polls async)	textarea suggestion under guest-details form	`notification-service`
Localized policy summarization	`ai-orchestrator-service`	`GET /policies` (cached, advisory)	small-print summary	`theme-config-service`
Currency-explanation tooltip	`ai-orchestrator-service`	`GET /availability`, `GET /quote`	tooltip on currency badge	`pricing-service`
Abandoned-cart copy (Phase 2+)	`ai-orchestrator-service`	not surfaced here; consumer is `notification-service`	n/a	`notification-service`

3. Calling pattern

SPA  ──►  bff-tenant-booking  ──►  ai-orchestrator-service  ──►  Vertex AI / cached model output
            (assemble VM)              (HITL gate, budget check, moderation)

The BFF treats ai-orchestrator-service as a regular upstream:

Deadline 1200 ms (advisory; degrades to non-AI VM on timeout).
Circuit breaker opens after 3 errors / 15 s; AI features disabled with aiUnavailable=true flag in response meta.
Budget rejected → suppress AI surface; no retry, no user banner (silent degrade).
HITL-required output → not surfaced on this BFF (HITL flows live in backoffice).

4. Prompt + model routing

This BFF authors no prompts. The orchestrator owns prompt templates. We pass:

interface AiRecommendationContext {
  capability: 'room.recommendation' | 'policy.summarization' | 'currency.explanation' | 'special_request.ack';
  tenantId: TenantId;
  bookingDraftId?: BookingDraftId;
  locale: string;
  currency: string;
  inputs: Record<string, unknown>;     // capability-specific
  guestSegment?: 'first_time' | 'returning' | 'vip';
}

Model selection (cloud Vertex AI vs cached output) is internal to the orchestrator; the BFF receives { output, provenance: { provenanceId, model, version, citedAt } }.

5. Telemetry annotations

When an AI-influenced response is rendered or acted upon, telemetry events carry an aiInfluence envelope field:

{
  "aiInfluence": {
    "provenanceIds": ["dec_01H8Y..."],
    "capabilities": ["room.recommendation"],
    "displayed": true,
    "interacted": false
  }
}

This is added to flow.step_completed.v1, booking.draft.created.v1, booking.draft.converted.v1, and confirmation.viewed.v1. Analytics joins on provenanceId to compute AI uplift.

6. Failure handling

Failure	Behavior
`ai-orchestrator-service` 5xx	Render the non-AI VM; set `meta.aiUnavailable=true`; emit one-shot `flow.error_encountered.v1` with `errorCode: MELMASTOON.AI.PROVIDER_UNAVAILABLE`
`MELMASTOON.AI.REFUSED_BUDGET`	Silently degrade (no banner, no telemetry noise); flag at admin dashboard via `ai-orchestrator-service`
`MELMASTOON.AI.REFUSED_SAFETY`	Silently degrade; orchestrator already audited; no user-facing surface
`MELMASTOON.AI.HITL_REQUIRED`	Not applicable (consumer-facing surface; HITL outputs are backoffice-only)
`MELMASTOON.AI.OUTPUT_INVALID`	Render fallback static copy; alert
Latency > 1200 ms	Skip AI; serve non-AI VM

7. PII handling toward the orchestrator

The BFF passes only:

tenantId, propertyId, roomTypeId (not PII).
guestSegment (categorical; not PII).
locale, currency.
For special-request ack: the user's free-text request (sent server-to-server with Content-Sensitivity: high header so orchestrator routes through PII-safe model variant).

The BFF NEVER sends email, phone, nationalIdNumber, firstName, lastName, or address to the orchestrator. If a capability ever needs them, that capability lives in ai-orchestrator-service itself and reads from reservation-service after appropriate consent.

8. Caching AI outputs

Capability	Cache scope	TTL
`room.recommendation`	Memorystore key `ai:rec:<tenantId>:<propertyId>:<dateRangeHash>:<guestSegment>`	10 min
`policy.summarization`	Memorystore key `ai:pol:<tenantId>:<policyHash>:<locale>`	24 h
`currency.explanation`	Memorystore key `ai:cur:<from>:<to>:<locale>`	24 h
`special_request.ack`	not cached (per-request)	n/a

Cache invalidation aligned with the upstream entity events (theme.published.v1, pricing.rate_plan.published.v1, etc.).

9. Feature flags

Flag	Default	Purpose
`ai.recommendations.enabled`	true	Master kill-switch
`ai.policy_summary.enabled`	true	Tenant opt-out per `tenant.config_updated.v1`
`ai.special_request_ack.enabled`	false (Phase 2+)	Defer until orchestrator phase
`ai.currency_tooltip.enabled`	true

Flags live in bff-tenant-flags Memorystore key; refreshed every 30 s.

10. Data residency

All AI calls flow through ai-orchestrator-service which enforces GCP region pinning (per 08 AI Architecture §6). The BFF never reaches Vertex AI directly.

11. Audit trail

For every AI-influenced surface, the orchestrator returns a provenanceId (dec_<ulid>). The BFF logs this to traces (span attribute ai.provenance.id) and includes it in telemetry envelopes. Audit trail reconstruction is therefore: trace → telemetry event → orchestrator decision row → model + version + prompt template.

12. Compliance notes

No autonomous AI mutations: every AI output is advisory or rendered — none mutates BookingDraft.flowState, BookingDraft.quote, or any upstream domain entity without an explicit user action.
HITL: out of scope for this BFF; backoffice handles HITL for tenants.
Sharia-compliant pricing constraints (per pricing-service): the BFF passes through complianceProfile if present and refuses to render any AI suggestion that omits the field on a Sharia-flagged tenant.

1. Posture​

2. AI capabilities surfaced​

3. Calling pattern​

4. Prompt + model routing​

5. Telemetry annotations​

6. Failure handling​

7. PII handling toward the orchestrator​

8. Caching AI outputs​

9. Feature flags​

10. Data residency​

11. Audit trail​

12. Compliance notes​