feat: SpacetimeDB Backend Sync

.env.example

@@ -22,3 +22,10 @@ NEXUS_COLLAB_SERVER_PORT=1234
 
 # Public WebSocket URL that browsers use to connect to the collab server.
 NEXT_PUBLIC_COLLAB_SERVER_URL=ws://localhost:1234
+
+# SpacetimeDB connection. When NEXT_PUBLIC_SPACETIME_URI is set, workspace mode
+# uses SpacetimeDB for persistence and real-time sync instead of the filesystem
+# REST API + Hocuspocus. Leave unset to keep the legacy persistence layer.
+NEXT_PUBLIC_SPACETIME_URI=ws://localhost:3001
+NEXT_PUBLIC_SPACETIME_DB_NAME=nexus
+SPACETIME_MODULE_PATH=spacetime/nexus

CLAUDE.md

@@ -64,6 +64,7 @@ Keep the mental model high-level:
 - `src/types/` — shared type definitions
 - `docs/tasks/` — task-specific plans and notes
 - `packages/` — auxiliary packages such as `nexus-acp-bridge`
+- `spacetime/nexus/` — SpacetimeDB TypeScript module (tables, reducers, lifecycle hooks)
 
 ---
 
@@ -93,6 +94,17 @@ Keep the mental model high-level:
 - Keep offline/editor-only flows working even when OpenCode is disconnected.
 - Client/service logic lives under `src/lib/opencode/`; related state lives under `src/store/opencode*`.
 
+### SpacetimeDB persistence and sync (workspace mode)
+- When `NEXT_PUBLIC_SPACETIME_URI` is configured, workspace mode uses SpacetimeDB for persistence and real-time collaboration instead of the filesystem REST API + Hocuspocus.
+- SpacetimeDB module definition: `spacetime/nexus/src/index.ts` — tables, reducers, lifecycle hooks for the SpacetimeDB 2.1 TypeScript module API.
+- Client-side sync bridges: `src/lib/spacetime/` — connection manager, workspace sync, brain sync, presence layer.
+- Generated SpacetimeDB client bindings live in `src/lib/spacetime/module_bindings/`. They are committed so app builds do not require the SpacetimeDB CLI; regenerate them with `scripts/generate-spacetime-bindings.sh` after module schema changes.
+- The sync bridges use the `_isApplyingRemote` loop-prevention pattern from `collab-doc.ts` to avoid feedback loops between SpacetimeDB subscriptions and Zustand store updates.
+- Hocuspocus/Yjs remains for standalone `?room=` collaboration mode.
+- REST API routes under `src/app/api/workspaces/` and `src/app/api/brain/` are deprecated shims; they will be removed once all clients use SpacetimeDB directly.
+- Standalone editor/localStorage mode is completely unaffected by SpacetimeDB.
+- New environment variables: `NEXT_PUBLIC_SPACETIME_URI`, `NEXT_PUBLIC_SPACETIME_DB_NAME`, `SPACETIME_MODULE_PATH`.
+
 ---
 
 ## Guardrails

Dockerfile

@@ -53,10 +53,13 @@ EXPOSE 3000
 
 COPY --from=builder --chown=bun:bun /app/public ./public
 
-# Install git for marketplace clone/pull operations at runtime.
-RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates \
+# Install git for marketplace clone/pull operations and curl for SpacetimeDB CLI.
+RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates curl \
     && rm -rf /var/lib/apt/lists/*
 
+# Install SpacetimeDB CLI for binding generation.
+RUN curl -fsSL https://install.spacetimedb.com | bash -s -- --yes 2>/dev/null || true
+
 RUN mkdir .next && chown bun:bun .next
 
 # Pre-create marketplace cache directory with correct ownership.

README.md

@@ -100,6 +100,32 @@ bun run docker:up
 bun run docker:down
 ```
 
+### Optional SpacetimeDB workspace backend
+
+Workspace mode can use SpacetimeDB for persistence and real-time sync. Standalone editor mode still uses browser storage.
+
+Start the SpacetimeDB service:
+
+```bash
+docker compose up nexus-spacetimedb -d
+```
+
+Publish the module and regenerate bindings after schema changes:
+
+```bash
+spacetime publish -p spacetime/nexus nexus
+./scripts/generate-spacetime-bindings.sh
+```
+
+Configure the app:
+
+```bash
+NEXT_PUBLIC_SPACETIME_URI=ws://localhost:30201
+NEXT_PUBLIC_SPACETIME_DB_NAME=nexus
+```
+
+Generated SpacetimeDB client bindings are committed under `src/lib/spacetime/module_bindings/`, so regular app builds do not need to run the SpacetimeDB CLI.
+
 ## Usage
 
 ### 1. Build a workflow

docker-compose.yml

@@ -15,6 +15,8 @@ services:
       PORT: "3000"
       NEXUS_BRAIN_DATA_DIR: /data/brain
       NEXT_PUBLIC_COLLAB_SERVER_URL: ws://localhost:1234
+      NEXT_PUBLIC_SPACETIME_URI: ws://localhost:${SPACETIME_PORT:-30201}
+      NEXT_PUBLIC_SPACETIME_DB_NAME: nexus
     expose:
       - "3000"
     volumes:
@@ -41,6 +43,20 @@ services:
       - nexus_collab_data:/data/collab
     restart: unless-stopped
 
+  # SpacetimeDB server (workspace persistence + real-time sync)
+  nexus-spacetimedb:
+    image: clockworklabs/spacetime:latest
+    container_name: nexus-spacetimedb
+    command: ["start"]
+    environment:
+      STDB_LOG_LEVEL: info
+    ports:
+      - "127.0.0.1:${SPACETIME_PORT:-30201}:3000"
+    volumes:
+      - nexus_spacetime_data:/var/lib/spacetimedb
+    restart: unless-stopped
+
 volumes:
   nexus_brain_data:
   nexus_collab_data:
+  nexus_spacetime_data:

docs/tasks/conditional_docs.md

@@ -13,3 +13,11 @@
     - When working with Brain document persistence, migration, import/export, or version restore
     - When modifying `src/app/api/brain/*` routes or the `src/lib/brain/*` storage/session layer
     - When troubleshooting persisted collaboration rooms, Hocuspocus startup, or share-link behavior
+
+- docs/tasks/feature-spacetimedb-backend-sync-feature/doc-feature-spacetimedb-backend-sync-feature.md
+  - Conditions:
+    - When working with SpacetimeDB integration, workspace persistence, or real-time sync
+    - When modifying files in `src/lib/spacetime/`, `spacetime/nexus/`, or workspace sync bridges
+    - When configuring `NEXT_PUBLIC_SPACETIME_URI` or SpacetimeDB Docker services
+    - When troubleshooting workspace mode persistence, multi-user collaboration, or presence
+    - When migrating data from filesystem-based workspaces to SpacetimeDB