Sync & Collaboration

StudioBrain is designed as a desktop-first application that works fully offline. For teams and individuals who want cloud access, paid tiers add sync, real-time collaboration, and cloud storage integrations.

Sync Overview

How Sync Works

StudioBrain uses a push/pull protocol to synchronize entity data between the desktop app and the cloud. The protocol is designed to be safe, deterministic, and conflict-aware.

The Push/Pull Protocol

Sync operates in discrete steps rather than continuous background replication:

1. Content hashing — Each entity file is hashed based on its content. The hash includes both the YAML frontmatter and the Markdown body.
2. Comparison — When you initiate a sync, the client sends its content hashes to the server. The server compares them against the cloud versions.
3. Delta exchange — Only changed entities are transferred. Unchanged entities are skipped entirely.
4. Conflict detection — If an entity was modified both locally and in the cloud since the last sync, it is flagged as a conflict rather than silently overwritten.
5. Apply and acknowledge — After changes are applied, both sides update their sync state.

Sync Modes

What Gets Synced

Initiating a Sync

From the desktop app:

1. Click the Sync button in the toolbar (or use the keyboard shortcut).
2. Review the sync summary showing how many entities will be pushed, pulled, or flagged.
3. Confirm to proceed.

Automatic sync can be enabled in Settings. When enabled, StudioBrain syncs periodically in the background (configurable interval, default 5 minutes).

From the system tray: The desktop app’s system tray icon shows sync status at a glance:

• Green check — synced and up to date
• Blue arrows — sync in progress
• Yellow warning — conflicts detected
• Red indicator — sync error

Conflict Resolution

Conflicts occur when the same entity is edited both locally and in the cloud between sync operations. StudioBrain never silently overwrites — it always surfaces conflicts for you to resolve.

How Conflicts Are Detected

A conflict is detected when:

• The local version of an entity has changed since the last sync, AND
• The cloud version of the same entity has also changed since the last sync

This is determined by comparing content hashes against the “last synced” baseline for each entity. When both sides have modified, the conflict resolver attempts to merge the changes automatically using a common ancestor (the last known version that both sides agree on). If a clean merge is not possible, the conflict is surfaced for manual review.

Automatic Resolution

When a conflict is detected, the server runs the conflict resolver — a deterministic, per-field merge engine that attempts to reconcile changes automatically before surfacing anything to you. The resolver classifies every field into one of four categories and applies the matching strategy:

If all fields resolve cleanly, the merged entity is saved automatically — no user action needed. If any field requires review, the entity is saved with the auto-resolved fields applied and the remaining conflicts surfaced in the Conflict Resolution view.

Manual Resolution

When the automatic resolver cannot resolve all fields (e.g., overlapping text edits without an ancestor, or differing binary attachments), StudioBrain opens the Conflict Resolution view:

1. Side-by-side diff — See the local version and the cloud version displayed side by side with differences highlighted.

2. Field-level comparison — For YAML frontmatter, individual fields are compared so you can see exactly which fields differ.

3. Conflict data preview — Each conflict shows the parsed entity content including:

   • Frontmatter fields — All YAML frontmatter (name, aliases, custom fields, etc.) parsed and displayed as structured key-value pairs
   • Markdown body — The entity’s content body shown beneath the frontmatter for full context
   • Timestamps — Last modified time for both local and remote versions
   • Content hashes — SHA-256 hashes used to detect the conflict

4. Resolution options:

   • Keep local — Use the local version, discard cloud changes
   • Keep cloud — Use the cloud version, discard local changes
   • Merge — Manually combine changes from both versions using the merge editor
   • Keep both — Create a copy of the entity, preserving both versions

5. Apply — After choosing a resolution for each conflict, click Apply to finalize.

Real-Time Presence (Team Tier)

Team and Enterprise subscribers get real-time presence — live visibility into who is editing what, powered by WebSocket connections.

What You See

• Active editors — See which team members are currently online
• Entity locks — See which entities are being edited and by whom
• Cursor presence — In the YAML and Markdown editors, see teammate cursors in real time
• Status indicators — Entity list pages show a presence badge when a teammate is editing an entity

How It Works

Real-time presence uses WebSocket connections to a Redis-backed PubSub system:

1. When you open an entity for editing, your session broadcasts a presence event.
2. Other users’ clients receive the event and display the presence indicator.
3. When you close the entity or navigate away, a departure event is broadcast.
4. Presence data is scoped to your tenant (team) — other teams cannot see your activity.

Editing the Same Entity

If two team members edit the same entity simultaneously:

1. Both users see each other’s presence indicators.
2. Edits are saved independently to each user’s local state.
3. When either user saves, the sync protocol handles merging.
4. If both save changes to the same fields, a conflict is surfaced for resolution.

StudioBrain does not support real-time co-editing of the same field (like Google Docs). Instead, it uses an optimistic concurrency model where each user works independently and conflicts are resolved at sync time.

Offline Mode

StudioBrain is fully functional offline. The desktop app uses a local SQLite database and local file storage — no server connection is needed for entity management, editing, or local AI features.

What Works Offline

• All entity CRUD operations (create, read, update, delete)
• Visual Editor, YAML Editor, Markdown Editor
• Validation Panel (rules are stored locally)
• Relationship Graph
• Cross-Entity Search
• Asset management (local files)
• AI generation with BYO API keys (if the AI provider is reachable)
• Local AI (Qwen) for free AI features
• Plugin functionality (locally installed plugins)

What Requires Connection

• Cloud sync (push/pull)
• Web app access
• Mobile app access
• Real-time presence
• Managed AI (BrainBits-based generation through StudioBrain Orchestrator)
• Google Drive sync
• BrainBits balance updates

Reconnecting

When you come back online:

1. StudioBrain detects the connection restoration.
2. If automatic sync is enabled, it initiates a sync immediately.
3. Any entities you modified offline are pushed to the cloud.
4. Any cloud changes from teammates are pulled down.
5. Conflicts are surfaced for resolution as normal.

All offline work is preserved — nothing is lost.

Google Drive Integration

Indie, Team, and Enterprise subscribers can connect Google Drive as a storage backend for additional backup and sharing.

Setting Up Google Drive

1. Go to Settings > Storage Providers.
2. Click Connect Google Drive.
3. Complete the Google OAuth consent flow. StudioBrain requests access to a dedicated folder in your Drive.
4. Select which project folders to sync.

What Gets Synced to Drive

StudioBrain creates a StudioBrain/ folder in your Google Drive and mirrors your project structure. Entity Markdown files, templates, and rules are synced automatically. Large binary assets can optionally be included.

Google Drive Quota

Google Drive storage counts against your Google account’s quota. StudioBrain entity files are small (typically under 50 KB each), so even large projects with thousands of entities use minimal Drive space.

Disconnecting Google Drive

To disconnect:

1. Go to Settings > Storage Providers.
2. Click Disconnect next to Google Drive.
3. Your local files are unaffected. Files already in Drive remain there until you delete them manually.

Storage Providers by Tier

Cloud index storage is limited by tier: 25 GB (Indie), 100 GB (Team), Unlimited (Enterprise).

Next Steps

• Mobile Sync Constraints — Mobile-specific sync behavior (cellular, battery, background)
• Getting Started — Overview of the application
• Settings & Configuration — Configure storage providers and sync settings
• Billing & Plans — Tier comparison and feature availability
• Installation — Desktop app setup and cloud connection