# XR Commerce Architecture

## Goal

Give shoppers an honest progression from a normal 2D store to private AI-assisted try-on, mobile AR and headset shopping without making the storefront depend on a headset or pretending flat product photography is a 3D fit model.

## Experience Ladder

### Phase 1 — 2D Fit Studio

Works on desktop and mobile without extra hardware.

- Local camera preview using browser media APIs
- Explicit consent before camera activation
- Pose framing and optional segmentation through MediaPipe Pose Landmarker
- Style profile based on stated preferences, fit and product attributes
- Manual compare mode for two authorized product images
- No biometric identification
- No upload by default

The current prototype implements camera activation and local framing only. Pose tracking and garment rendering are not represented as complete.

### Phase 2 — AI Garment Rendering

- Shopper chooses camera capture or uploaded image
- Consent screen explains processing, retention and limitations
- Temporary render session gets a random identifier
- Authorized garment image, mask and size metadata are sent to the try-on service
- Generated output is labeled as a visualization, not a fit guarantee
- Original and output images expire automatically under the approved retention policy
- Users can delete the session immediately

AI recommendation and visual rendering are separate services. A strong visual match must not be presented as evidence that the physical size will fit.

### Phase 3 — Product AR

- Every supported SKU receives a dimensionally validated GLB asset
- iOS receives a corresponding USDZ asset for Quick Look
- Android uses Scene Viewer with a 3D fallback
- WebXR is capability-detected rather than assumed
- Boots, belts, buckles, wallets and bags launch first because rigid products are easier to represent accurately
- Garments launch only when drape, sizing and body-occlusion quality pass review

### Phase 4 — Headset Store

- WebXR showroom route with a 2D DOM overlay for navigation and cart actions
- Meta Quest and compatible immersive browsers receive room-scale presentation
- Apple Vision Pro receives the supported Safari WebXR path and graceful 2D fallback
- Hand and controller input map to the same accessible product actions
- Shoppers can move an outfit from phone or desktop into the headset session through a short-lived handoff code

## FANZ Stack Integration

```text
Storefront
  -> catalog gateway
     -> @fanz/supplier-pool
     -> fanz_core product, supplier and authorization records
  -> style service
     -> product attributes and shopper-declared preferences
  -> try-on gateway
     -> consent record
     -> temporary render queue
     -> AI rendering worker
  -> XR asset gateway
     -> GLB, USDZ, dimensions and version manifest
```

Suggested routes:

- `GET /api/catalog`
- `GET /api/catalog/:sku/xr`
- `POST /api/style-profile`
- `POST /api/try-on/session`
- `POST /api/try-on/render`
- `DELETE /api/try-on/session/:id`
- `POST /api/xr/handoff`

## Data Placement

- PostgreSQL `fanz_core`: durable catalog, supplier authorization, consent receipts and non-sensitive style preferences
- Redis: temporary sessions, render queues, rate limits and headset handoff codes
- Object storage: authorized product media and versioned 3D assets
- Temporary try-on media: isolated encrypted storage with enforced expiration, never a permanent profile field by default

## Device Strategy

- Baseline: responsive 2D commerce remains complete and accessible
- Web pose: MediaPipe Pose Landmarker can return image landmarks, 3D world landmarks and an optional segmentation mask
- Android AR: `<model-viewer>` can route to WebXR or Scene Viewer
- iOS AR: `<model-viewer>` can route to AR Quick Look using USDZ
- Headsets: WebXR is used only after `isSessionSupported()` confirms the requested mode

WebXR remains limited across mainstream browsers, so immersive features are an enhancement rather than a checkout dependency.

## Privacy and Safety Gates

- Camera disabled until a direct user action
- Clear local-versus-uploaded processing indicator
- No facial recognition or identity inference
- No age, race, health or sexuality inference from images
- No try-on media in analytics events or logs
- Request IDs and structured errors without image payloads
- Rate limits on upload and rendering endpoints
- Signed URLs with short expiration
- Accessible non-camera alternative for every product flow
- Security and privacy review before any public beta

## Product Asset Acceptance

An AR-ready product is not simply a `.glb` file. Each asset must include:

- real-world dimensions and unit scale
- SKU and colorway linkage
- material names and texture licenses
- polygon and texture budgets for mobile and headset profiles
- GLB validation
- USDZ validation where applicable
- neutral lighting QA
- occlusion and placement QA
- version, checksum and rollback reference

## Technical References

- [W3C WebXR Device API](https://www.w3.org/TR/webxr/)
- [Google ARCore Scene Viewer](https://developers.google.com/ar/develop/scene-viewer)
- [`<model-viewer>` documentation](https://modelviewer.dev/docs/index.html)
- [MediaPipe Pose Landmarker](https://developers.google.com/edge/mediapipe/solutions/vision/pose_landmarker)