Workspace Sync Module

The Workspace Sync module provides cloud storage for all content files (profiles, onboarding data, memory, artifacts) and a real-time SSE change feed. Source: packages/server/src/modules/workspace-sync/.

REST Endpoints

All endpoints are prefixed with /api/v1/sync and require ClerkAuthGuard.

Profile & Onboarding

Method	Path	Description
PUT	`/sync/profile`	Store user profile JSON
GET	`/sync/profile`	Retrieve user profile JSON
PUT	`/sync/org-onboarding`	Store org onboarding JSON
GET	`/sync/org-onboarding`	Retrieve org onboarding JSON

Memory

Method	Path	Description
PUT	`/sync/memory/:scope`	Store memory (scope: `user` or `org`)
GET	`/sync/memory/:scope`	Retrieve memory
PUT	`/sync/memory/workspace/:workspaceId/:fileName`	Store workspace memory file
GET	`/sync/memory/workspace/:workspaceId/:fileName`	Get workspace memory file
GET	`/sync/memory/workspace/:workspaceId`	List workspace memory files

Files (General)

Method	Path	Description
POST	`/sync/files`	Upload a file
GET	`/sync/files/:id`	Download file content
GET	`/sync/files`	List files (with filters)
DELETE	`/sync/files/:id`	Delete a file
PUT	`/sync/files/:id`	Update file content

Query params for GET /sync/files:

Param	Description
`kind`	`StorageKind` filter
`scope`	`SHARED` or `PERSONAL`
`workspaceId`	Filter by workspace
`prefix`	Key prefix filter

Manifest & Changes

Method	Path	Description
GET	`/sync/manifest`	Get metadata index for the whole org
GET	`/sync/changes`	SSE change feed

Workspace Sync Service (`services/workspace-sync.service.ts`)

Storage Layout

All blobs are stored in R2/S3 under an org-scoped path:

/{orgId}/shared/hub-memory/          ← Org-level AI memory
/{orgId}/shared/brand/               ← Logos, icons
/{orgId}/shared/templates/           ← Shared templates
/{orgId}/teams/{teamId}/memory/      ← Team memory files
/{orgId}/workspaces/{workspaceId}/   ← Workspace artifacts + memory
/{orgId}/personal/{userId}/          ← Personal files + user memory

Profile & Onboarding Methods

Method	Description
`putUserProfile(orgId, userId, data)`	Write `profile.json` to personal scope
`getUserProfile(orgId, userId)`	Read `profile.json`; returns parsed object or `null`
`putOrgOnboarding(orgId, data, userId)`	Write `org.json` to shared scope
`getOrgOnboarding(orgId)`	Read `org.json`; returns parsed object or `null`

Memory Methods

Method	Description
`putMemory(orgId, userId, scope, content)`	Store `user-memory.md` or `org-memory.md`
`getMemory(orgId, userId, scope)`	Retrieve memory file content
`putWorkspaceMemory(orgId, workspaceId, fileName, content, userId)`	Store named file in workspace memory dir
`getWorkspaceMemory(orgId, workspaceId, fileName)`	Retrieve workspace memory file
`mergeWorkspaceMemory(orgId, workspaceId, fileName, content, userId, expectedVersion)`	Merge with optimistic version check; throws `409` on conflict
`listWorkspaceMemory(orgId, workspaceId)`	List all memory files in workspace

File Methods

Method	Description
`putFile(orgId, blobPath, buffer, mimeType, metadata)`	Upload blob + create `StorageObject` metadata record
`getFile(orgId, id)`	Returns `{ body: Buffer, metadata: StorageObject }`
`deleteFile(orgId, id, userId)`	Remove blob + delete metadata record
`listFiles(orgId, filters)`	Query `StorageObject` table with optional filters
`updateFile(orgId, id, buffer, userId)`	Replace blob + bump version + update checksum

Manifest

getManifest(orgId) returns an array of all StorageObject metadata records for the org. Used by the desktop client to detect stale local files without downloading them.

SSE Change Feed

GET /api/v1/sync/changes opens a Server-Sent Events connection.

Server sends a heartbeat comment every 30 seconds to keep the connection alive through proxies.
When any file changes (via putFile, deleteFile, updateFile, putMemory, etc.), the service calls notifyChange(orgId, event).
All connected clients for that orgId receive the event.

Change event structure:

{
  type: 'file-changed' | 'file-deleted';
  storageKey: string;    // R2/S3 key
  path: string;          // Logical path
  checksum?: string;     // SHA-256 (on change)
  version?: number;      // New version number
  changedBy?: string;    // userId who made the change
  timestamp: string;     // ISO timestamp
}

Storage Kinds

Kind	Description
`ARTIFACT`	AI-generated documents, reports, dashboards
`HUB_MEMORY`	Org-level AI memory
`TEAM_MEMORY`	Team-scoped AI memory
`WORKSPACE_MEMORY`	Workspace-scoped AI memory
`TEMPLATE`	Reusable templates
`BRAND_ASSET`	Logos, icons, brand images

Storage Scopes

Scope	Description
`SHARED`	Visible to all team members
`PERSONAL`	Visible only to the owning user

Blob Storage Provider (`services/blob-storage.provider.ts`)

Wraps the R2/S3 SDK with a consistent interface:

Method	Description
`getBlob(key)`	Download a blob by key
`putBlob(key, body, metadata)`	Upload a blob
`deleteBlob(key)`	Delete a blob
`listBlobs(prefix)`	List blobs under a prefix
`headBlob(key)`	Get blob metadata without downloading

Workspace Sync Module

On this page