Paytial is a spatial commerce demo built with Next.js, React, TypeScript, and WebSpatial. It showcases a product-led shopping flow where users can pull products into a 3D model stage, inspect and rotate them naturally, receive AI-generated sales guidance, and execute a checkout flow that returns proof-style settlement metadata.

Paytial is designed as a practical reference for teams building immersive retail experiences across web and spatial runtimes.

Core ideas:

• Bring catalog items into a central model stage as interactive 3D objects.
• Let users manipulate models directly (grab-and-rotate) to simulate in-store product handling.
• Use AI context to generate sales framing and recommendations from interaction signals.
• Connect UI actions to checkout and settlement proof endpoints.

This repo is not only a UI mock. It also includes an API scaffold and data flow that can be extended into production with real AI, payments, analytics, and fulfillment systems.

• Interactive 3D model stage with product-specific model loading.
• Continuous auto-spin plus direct drag rotation in the same direction as user movement.
• Multi-product model support (phone, speaker, display, rug).
• AI analysis panel with contextual summary, intent, and talking points.
• Checkout panel with proof payload simulation and settlement metadata.
• Local API routes for pipeline orchestration, voice streaming, and checkout actions.

1. User opens the listings panel.
2. User selects a product card to pull it into the model stage.
3. Product model appears, auto-spins, and can be rotated manually by dragging.
4. AI panel updates with context-aware persuasion points.
5. User initiates checkout.
6. App returns a proof-style settlement object for confirmation UX.

Retailers can let customers inspect product shape, finish, and proportions in 3D before purchase.

In-store associates can use AI talking points while customers manipulate 3D product models live.

Sales teams can share sessions via Cloudflare Tunnel for guided demos without full deployment.

Teams can load multiple product categories and compare model engagement and AI conversion suggestions.

UX, frontend, and platform teams can use this repo as a foundation for WebSpatial interaction patterns.

Developers can test pipeline orchestration and checkout UX with realistic request/response contracts.

Frontend:

• Next.js App Router UI in app/
• Spatial commerce feature modules in app/features/spatial-commerce/
• 3D stage renderer with product model mapping and interaction logic

Backend scaffold:

• POST /api/pipeline: context + pitch + voice + checkout orchestration
• GET /api/pipeline: lightweight health check
• GET/POST /api/voice/stream: ElevenLabs voice proxy surface
• GET/POST /api/actions/checkout: action creation and settlement simulation

Domain services:

• lib/spatialpay/: agents and orchestration utilities
• database/schema.sql: data model for merchants, sessions, gaze, pitch, voice, and checkout events

Current model assets are served from public/ and mapped per product in app/features/spatial-commerce/utils.ts.

Mapped products:

• Aster Phone 17 -> /cellphone.glb
• Nimbus Smart Speaker -> /bluetooth_speaker.glb
• Halo 65 Display -> /computer_monitor_lowpoly_model.glb
• Mesa Area Rug -> /rug_with_bottom.glb

Behavior:

• Auto-rotate when idle.
• User drag rotates model freely on X/Y with no fixed degree limit.

• pnpm dev
• pnpm dev:host
• pnpm dev:webspatial
• pnpm tunnel
• pnpm build
• pnpm start
• pnpm lint
• pnpm docker:build
• pnpm docker:run

1. Install dependencies.

pnpm install

2. Start app.

pnpm dev

3. Open http://localhost:5173.

4. Optional: expose app for remote testing.

pnpm tunnel

This project can be deployed as a containerized app on Vultr. The flow below keeps the app functional through build, publish, app creation, and release verification.

pnpm docker:build
docker run --rm -p 5173:5173 --env-file .env.local webspatial-starter:latest

In a second terminal, confirm the app is healthy:

curl -i http://localhost:5173
curl -i http://localhost:5173/api/pipeline

If both return success, proceed.

Tag and push the image to your chosen registry:

docker tag webspatial-starter:latest REGISTRY_HOST/NAMESPACE/webspatial-starter:latest
docker login REGISTRY_HOST
docker push REGISTRY_HOST/NAMESPACE/webspatial-starter:latest

Registry options include Vultr Container Registry, Docker Hub, and GHCR.

In the Vultr dashboard:

1. Go to Products -> App Platform, or Cloud Compute if you prefer a VM.
2. Choose deploy from existing container image.
3. Set the image URL to REGISTRY_HOST/NAMESPACE/webspatial-starter:latest.
4. Set the container port to 5173.
5. Use the smallest instance size for the demo first, then scale later if needed.

Copy the required keys from your local .env.example or environment setup and add them in the Vultr app settings.

At minimum set:

• SNOWFLAKE_ACCOUNT
• SNOWFLAKE_USERNAME
• SNOWFLAKE_PASSWORD
• SNOWFLAKE_WAREHOUSE
• SNOWFLAKE_DATABASE
• SNOWFLAKE_SCHEMA
• ELEVENLABS_API_KEY
• ELEVENLABS_VOICE_ID
• NEXT_PUBLIC_SOLANA_RECEIVER_ADDRESS
• SOLANA_NETWORK
• SOLANA_RPC_URL

Set NEXT_PUBLIC_SITE_URL to your final Vultr domain, not localhost.

• Health path: /api/pipeline
• Use HTTP first, then enable HTTPS/domain.
• Deploy and wait for the app to reach active status.

• Point your domain A record to the Vultr endpoint, or use the Vultr-provided domain.
• Enable the TLS certificate in Vultr.

Open the deployed domain and confirm these endpoints load successfully:

https://YOUR_DOMAIN/
https://YOUR_DOMAIN/api/pipeline

Also confirm checkout and action URLs are using the deployed domain.

Repo-specific notes:

• Docker scripts are already defined in package.json.
• Vultr deployment guidance lives here in the README for quick copy/paste.
• Docker image configuration is in Dockerfile.

SNOWFLAKE_ACCOUNT="your_account_identifier"
SNOWFLAKE_USERNAME="your_username"
SNOWFLAKE_PASSWORD="your_password"
SNOWFLAKE_WAREHOUSE="COMPUTE_WH"
SNOWFLAKE_DATABASE="SPATIAL_PAY_DB"
SNOWFLAKE_SCHEMA="PUBLIC"
SNOWFLAKE_CORTEX_MODEL="mistral-small-2603"

When set, the pipeline can use Snowflake Cortex. Without them, local deterministic fallback keeps the demo functional.

{
  "userId": "user-123",
  "sessionId": "session-123",
  "merchantId": "merchant-123",
  "voiceId": "optional-voice-id",
  "gazeData": [
    {
      "x": 0.52,
      "y": 0.18,
      "depth": 0.62,
      "dwellMs": 1600,
      "targetId": "product-slate",
      "confidence": 0.91
    }
  ],
  "product": {
    "id": "product-001",
    "merchantId": "merchant-123",
    "name": "Aurora Chair",
    "price": 249,
    "currency": "USD"
  }
}

Use local docs in docs/ as primary reference.

• Start: Getting Started
• Concepts: Spatial Computing, Spatial Scenes, Spatialized HTML Elements, 3D Content Containers
• React components: Model, Reality, JSX Markers
• Builder CLI: run, build, publish

Paytial demonstrates how spatial UX, AI-guided selling, and commerce actions can be combined into one coherent product experience. It is a useful base for:

• spatial storefront pilots,
• conversational commerce demos,
• B2B product visualization,
• and checkout flow prototyping with proof-ready transaction UX.