SpacetimeDB Setup

Enable real-time synchronization for Pixel Office and live telemetry

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Pixel Office  │────▶│   SpacetimeDB    │◀────│  SeaClip Hub    │
│   (React UI)    │     │   (Real-time)    │     │  (Express API)  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        │                       │                        │
        │  useTable() hooks     │  Reducers              │  Telemetry
        │  Auto-sync            │  WebSocket             │  Agent updates
        ▼                       ▼                        ▼
   Live visualization    Persistent state         Edge devices
        

SeaClip uses a hybrid database architecture:

• PostgreSQL — Core business data (companies, agents, tickets, costs, audit)
• SpacetimeDB — Real-time visualization and telemetry streaming

One-Line Setup

cd /opt/seaclip
./scripts/setup-spacetimedb.sh

This script will:

1. Install SpacetimeDB CLI
2. Install Rust (if needed)
3. Build the SpacetimeDB module
4. Publish to SpacetimeDB cloud
5. Generate TypeScript bindings

Manual Setup

Step 1: Install SpacetimeDB CLI

curl -sSf https://install.spacetimedb.com | sh

Step 2: Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
rustup target add wasm32-unknown-unknown

Step 3: Build the Module

cd /opt/seaclip/spacetimedb
spacetime build

Step 4: Login to SpacetimeDB

spacetime login

This opens a browser for authentication. After login, you'll receive a token.

Step 5: Publish the Module

spacetime publish seaclip-realtime

Step 6: Generate TypeScript Bindings

spacetime generate seaclip-realtime --lang typescript --out-dir ../ui/src/lib/spacetimedb/generated

SpacetimeDB Tables

Pixel Office Tables

Hub-Spoke Tables

Agent Call Tables

Reducers (Server Functions)

SpacetimeDB reducers are server-side functions that modify the database:

Pixel Office

• upsert_pixel_agent — Register/update agent
• move_agent — Update agent position
• update_agent_activity — Update agent state/activity
• remove_pixel_agent — Remove agent

Hub-Spoke

• upsert_edge_device — Register/update device
• record_telemetry — Record telemetry data
• set_device_offline — Mark device offline

Agent Calls

• start_call — Start a new call
• join_call — Join an existing call
• send_call_message — Send a message
• end_call — End a call

Using in React

Import the hook in your React components:

import { usePixelOfficeDB } from '@/lib/spacetimedb';

function PixelOffice() {
  const { 
    connected,
    agents,
    upsertAgent,
    moveAgent,
    updateActivity,
  } = usePixelOfficeDB();
  
  // Agents sync in real-time automatically
  return (
    <div>
      {connected ? '🟢 Connected' : '🟡 Connecting...'}
      {agents.map(agent => (
        <AgentSprite key={agent.id} agent={agent} />
      ))}
    </div>
  );
}

SpacetimeDB Dashboard

View your data at:

https://spacetimedb.com/seaclip-realtime

The dashboard shows:

• All tables and their data
• Real-time updates as they happen
• Query interface for debugging
• Connection statistics

Verify Integration

1. Open Pixel Office

   Navigate to http://localhost:5173/pixel-office

2. Check connection status

   Look for the green "Real-time sync active" indicator

3. Open SpacetimeDB dashboard

   Check that pixel_agent table has 9 rows

4. Check browser console

   Look for [SpacetimeDB] Connected with identity: message

Troubleshooting

Next Steps