# Hospitality API Connection Report

**Date:** 2026-07-26

## Connection path

```
Browser → /api/hospitality/* (BFF) → hospitality-service:8009
Headers: Authorization, X-Tenant-ID
Client: modules/hospitality/services/hospitality-api.ts
```

## Resources wired

All 50 registry entries call `hospitalityApi.*` methods — no mocks.

| API group | Endpoints used |
|-----------|----------------|
| Foundation | venues, branches, diningAreas, tables |
| Catalog | menus, menuCategories, menuItems, modifierGroups, modifierOptions, availabilityWindows, menuMediaRefs |
| QR | qrCodes, qrMenuSessions, qrOrderingSessions, carts, cartLines |
| Table service | reservations, waitlist |
| Kitchen | kitchenTickets, kitchenTicketItems |
| POS Lite/Pro | posRegisters, posTickets, posPayments, posDiscounts, posFloorPlans |
| Connectors | connectorRegistrations, connectorDispatches |
| Analytics | analyticsReports, analyticsSnapshots |
| Admin | settings, permissions, roles, events, tenantBundles, featureToggles |
| Platform | health, capabilities |

## Workflow endpoints

| UI action | API call |
|-----------|----------|
| Confirm reservation | `POST /api/v1/reservations/{id}/status` |
| Submit QR order | `POST /api/v1/qr-ordering-sessions/{id}/submit` |
| Kitchen ready | `POST /api/v1/kitchen-tickets/{id}/status` |
| Void POS ticket | `POST /api/v1/pos-tickets/{id}/void` |
| Deactivate bundle | `POST /api/v1/tenant-bundles/{id}/deactivate` |
| Upsert setting | `POST /api/v1/settings/upsert` |

## Real-time pages

| Page | refetchInterval |
|------|-----------------|
| kitchen/display | 5000ms |
| kitchen/queue | 5000ms |
| kitchen/preparation | 5000ms |
| orders/timeline | 8000ms |
| dashboard | 30000ms |
| health | 15000ms |

## Error handling

- `HospitalityApiError` → 403 shows permission empty state
- Network errors → Persian message with URL
- 401 → token refresh retry
- Mutations → toast success/error via sonner

## Validation

- TypeScript: hospitality module passes `tsc --noEmit`
- All buttons invoke real `useMutation` / `useQuery` handlers
- No `TODO`, no `mock`, no `fake` in feature layer