ai-chatbot/apps/editor/features/cloud-sync

Cloud Sync Feature

This directory contains the optional cloud synchronization and authentication features for the Pascal Editor. This feature is specific to the Pascal platform and can be safely removed if you're using the editor standalone.

What This Does

The cloud sync feature provides:

• Authentication - Sign in with magic link via Better Auth
• Property Management - Create and manage properties with Google Maps address search
• Scene Loading - Automatically load property scenes from the database when a property is selected
• Auto-Save - Automatically save scene changes to the database (2-second debounce)
• Database Sync - Save and load editor state from a PostgreSQL database via Supabase

Architecture

features/cloud-sync/
├── lib/
│   ├── auth/
│   │   ├── client.ts          # Better Auth client configuration
│   │   ├── server.ts          # Server-side session handling
│   │   └── hooks.ts           # useAuth React hook
│   ├── properties/
│   │   ├── actions.ts         # Server actions for CRUD operations
│   │   ├── types.ts           # TypeScript types for properties
│   │   └── hooks.ts           # useProperties and useActiveProperty hooks
│   ├── database/
│   │   └── server.ts          # Supabase server client with service role
│   └── utils/
│       └── id-generator.ts    # nanoid-based ID generation (matches backend)
├── components/
│   ├── cloud-save-button.tsx  # Main UI entry point (top-right button)
│   ├── sign-in-dialog.tsx     # Magic link sign-in dialog
│   ├── profile-dropdown.tsx   # User profile menu
│   ├── property-dropdown.tsx  # Property selector dropdown
│   ├── new-property-dialog.tsx # Create new property dialog
│   └── google-address-search.tsx # Google Maps autocomplete
└── README.md                   # This file

How It Works

Authentication Flow

1. User clicks "Save to cloud" button
2. Signs in with magic link (email-based, no password)
3. Better Auth session is stored in cookies
4. Server actions validate session by calling the monorepo backend

Property Management

1. User creates a property with a real-world address (Google Maps)
2. Address and property are saved to PostgreSQL via Supabase
3. Properties are associated with the authenticated user
4. User can switch between properties

Scene Management

1. When a property is selected, its scene is loaded from properties_models table
2. If no scene exists, loads default empty scene
3. Scene changes are auto-saved every 2 seconds (debounced)
4. Updates existing model (highest version) instead of creating new ones
5. Scene graph includes all nodes and hierarchy

Database Integration

• Uses Supabase (PostgreSQL) for database access
• Server actions use service role key to bypass RLS
• Permissions enforced by filtering on owner_id
• Table names: properties, properties_addresses, auth_sessions

Required Environment Variables

# Backend API URL (Pascal monorepo - for better-auth only)
NEXT_PUBLIC_API_URL=http://localhost:3000

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key_here
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_here

# Google Maps API Key (for address search)
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your_google_maps_key_here

Dependencies

The cloud sync feature requires these packages:

{
  "better-auth": "^1.4.18",
  "@supabase/supabase-js": "^2.95.3",
  "@react-google-maps/api": "^2.20.8",
  "nanoid": "^5.1.6"
}

How to Remove (For Open Source Users)

If you want to use the editor without cloud sync:

1. Delete this directory

rm -rf features/cloud-sync

2. Remove the CloudSaveButton from the editor

Edit components/editor/index.tsx:

- import { CloudSaveButton } from '@/features/cloud-sync/components/cloud-save-button'

  export default function Editor() {
    return (
      <div className="w-full h-full">
        <ActionMenu />
        <PanelManager />
-       <CloudSaveButton />

3. Remove dependencies (optional)

Edit package.json:

- "better-auth": "^1.4.18",
- "@supabase/supabase-js": "^2.95.3",
- "@react-google-maps/api": "^2.20.8",
- "nanoid": "^5.1.6"

4. Remove environment variables

Delete from .env.local and .env.example:

- NEXT_PUBLIC_API_URL=...
- NEXT_PUBLIC_SUPABASE_URL=...
- NEXT_PUBLIC_SUPABASE_ANON_KEY=...
- SUPABASE_SERVICE_ROLE_KEY=...
- NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=...

That's it! The editor will work as a standalone application without any cloud features.

Backend Requirements

This feature requires the Pascal monorepo backend running with:

• Better Auth configured with magic link support
• PostgreSQL database with the following tables:
  • properties - Property records
  • properties_addresses - Property addresses
  • auth_sessions - Better Auth sessions
  • auth_users - Better Auth users
• Supabase local instance for database access

Development

To work on this feature:

1. Ensure the monorepo backend is running on port 3000
2. Ensure Supabase local is running on port 54321
3. Configure all environment variables
4. Run the editor: bun dev

The editor will be available at http://localhost:3002 (different port to avoid conflicts with the monorepo).

Notes

• This feature uses server actions (Next.js App Router) for all database operations
• Authentication is handled by the monorepo backend via Better Auth
• The editor queries the database directly using Supabase with service role key
• IDs are generated using nanoid with custom alphabet to match the backend schema
• All table names match the monorepo's database schema exactly