TorbatYar/frontend/docs/beauty-api-connection-report.md

Beauty API Connection Report

Date: 2026-07-26
Client: modules/beauty/services/beauty-business-api.ts
BFF: /api/beauty-business/* → :8011

---

Connection Architecture

Browser (beauty pages)
  → beautyBusinessApi (tenant + JWT)
  → Next.js BFF /api/beauty-business/[...path]
  → beauty-business-service :8011

No mock data. All list/create/mutation calls use beautyBusinessApi with X-Tenant-ID and Bearer token.

---

API Resources — Frontend Coverage

API Resource	Methods in Client	UI Surfaces
/health, /capabilities, /metrics	GET	Hub, dashboards, monitoring
organizations	list, get, create, update, delete	Owner, admin
branches	list, get, create, update, delete	Owner, admin, booking forms
customers	list, get, create	Owner, admin, customer portal, booking
staff	list, get, create	Owner, admin, staff portal, schedules
service-categories	list, get, create	Owner catalog
services	list, get, create	Owner catalog, public site, booking
staff-schedules	list, get, create	Owner booking, staff portal
waiting-list	list, get, create	Owner, reception queue/walk-in
treatment-rooms	list, get, create	Owner salon
stations	list, get, create	Owner salon
branch-policies	list, get, create	Owner salon
package-definitions	list, get, create	Owner, customer, public
membership-plans	list, get, create	Owner, customer
commission-rules	list, get, create	Owner, staff commission page
marketing-campaigns	list, get, create	Owner, public campaigns
loyalty-integrations	list, get, create	Owner integrations tab
communication-integrations	list, get, create	Owner integrations tab
integration-dispatches	list, get, create	Owner integrations tab
appointments	list, get, create, update, confirm, check-in, complete, cancel, no-show, history	Owner, reception, customer, staff, public book
settings	list, upsert	Owner settings, admin settings
permissions/catalog	GET	Owner settings, admin permissions
audit	list	Workspace detail drawers
external-providers	list, get, create, update, delete	Owner integration pages

---

Workflow Actions Connected

Action	API Endpoint	UI Trigger
Confirm appointment	POST .../confirm	Owner table, reception check-in
Check-in	POST .../check-in	Owner table, reception check-in
Complete	POST .../complete	Owner table, reception check-out
Cancel	POST .../cancel	Owner table, reception
No-show	POST .../no-show	Owner table, reception

---

Cross-Module Integrations (Real Links, Not Mocks)

UI Surface	External Module	Behavior
Customer invoices/payments	/accounting/*	Navigation + empty state
Customer loyalty	Loyalty API via beauty integrations list	Read from loyaltyIntegrations
Reception payments	/accounting	Explicit link
Owner CRM/accounting integration	externalProviders filtered by kind	Real list from API

---

API Methods Not in Backend (Documented)

These permissions exist in backend definitions but routes are create/list/get only — client has no update/delete stubs:

• customers, staff, service-categories, services, schedules, waiting-list, rooms, stations, policies, packages, memberships, commissions, marketing campaigns, integrations

When backend adds PATCH//delete, add methods to beauty-business-api.ts and enable updateFn/deleteFn in resource configs.

---

TanStack Query Keys

Pattern: ["beauty", tenantId, resource, ...params]
Lookups: ["beauty", tenantId, "lookups", entity]
Invalidation on mutation: resource queryKey + lookups

---

Error Handling

• BeautyBusinessApiError → toast message + ErrorState retry
• 401 → session refresh via getValidAccessToken / refreshSession
• 403 → PermissionDeniedState
• Network failure → Persian connection error message