Realtime Collaboration
Relevant source files
The following files were used as context for generating this wiki page:
ThinkEx is designed as a visual thinking environment where context is explicit, organized, and persistent. Realtime collaboration within this ecosystem ensures that as users spread out media, notes, and AI conversations on a spatial canvas, the state of the workspace—including item placements, content updates, and version history—remains synchronized across participants.
The system utilizes a tech stack comprising Next.js for the framework, PostgreSQL with Drizzle ORM for the database, and Zustand for state management. Collaboration is facilitated through a robust event-driven architecture where workspace changes are captured as discrete events, allowing for features like shared context and version rollbacks.
Sources: README.md:46-60, src/components/workspace/VersionHistoryModal.tsx:327-340
Workspace Event System
The core of collaboration in ThinkEx is an append-only event log. Every significant action within a workspace—from creating a document to moving a folder—is recorded as a WorkspaceEvent. This log serves as the single source of truth for the current state and history of the workspace.
Event Types and Descriptions
The system tracks various event types to maintain synchronization and provide a detailed audit trail.
| Event Type | Description | Relevant Payload Data |
|---|---|---|
WORKSPACE_CREATED | Initial creation of the environment. | Title, description |
ITEM_CREATED | Addition of a new PDF, document, or card. | Item object (type, name) |
ITEM_UPDATED | Modification of existing content or metadata. | Item ID, name, changes |
ITEM_DELETED | Removal of an item from the canvas. | Item ID, name |
BULK_ITEMS_UPDATED | Batch updates, often used for layout changes. | Deleted IDs, layout updates |
WORKSPACE_SNAPSHOT | Periodic saving of the entire workspace state. | Full state capture |
FOLDER_CREATED_WITH_ITEMS | Creating a folder containing existing items. | Folder object, item IDs |
Sources: src/components/workspace/VersionHistoryModal.tsx:40-160, src/app/api/workspaces/autogen/route.ts:400-420
Event Processing Flow
When an action occurs (e.g., AI autogeneration), the server appends a workspace event to the database. This event includes a unique ID, the operation type, payload, timestamp, and user identification.
The diagram shows how actions are serialized into the event log and subsequently propagated to update the visual workspace.
Sources: src/app/api/workspaces/autogen/route.ts:403-415
AI Context and Shared State
Realtime collaboration extends to how the AI perceives the workspace. The AI assistant is provided with a "Workspace FS" (File System) that reflects the current state of all items, including their paths and metadata. This ensures that the AI is always working with the most up-to-date version of the user's collaborative environment.
Workspace Context Formatting
The system generates a <system> block for the AI that includes:
- Role and Identity: Identifying as a ThinkEx assistant.
- Time and Knowledge: Current date and knowledge cutoff.
- Context Prioritization: Identifying items "currently viewing" or "selected cards" to focus the AI's attention.
- Workspace Metadata: A full list of paths and metadata for all items in the workspace.
This sequence illustrates how collaborative context is synchronized with the AI during a chat session.
Sources: src/app/api/chat/route.ts:250-300, src/app/generate/page.tsx:85-120
Versioning and State Restoration
A critical component of collaborative workspaces is the ability to track changes and revert to previous states. ThinkEx implements a version history mechanism based on the WorkspaceEvent sequence.
Version History Modal
The VersionHistoryContent component renders the list of historical events, allowing users to see who made what change and when. Each event is associated with a version number.
- User Tracking: Events store
userIdanduserName(or email) to attribute actions to specific collaborators. - Revert Logic: Users can revert to a specific version. This typically involves restoring the state to the point before a selected event occurred (Version - 1).
- Visual Indicators: The UI highlights the "Current" version and provides distinctive icons for different operation types (e.g., emerald for creation, amber for updates, red for deletions).
Sources: src/components/workspace/VersionHistoryModal.tsx:280-325, src/components/workspace/VersionHistoryModal.tsx:350-400
Collaborative Content Autogeneration
The autogen system demonstrates high-concurrency collaboration between the user, the server, and multiple AI agents. While a workspace is being generated from a prompt, the system streams progress events to the client.
| Stage | Description | Technical Action |
|---|---|---|
understanding | AI analyzes the prompt and attachments. | Runs distillation agent. |
metadata | Generates title, icon, and theme color. | Updates workspaces table. |
workspace | Initial workspace record creation. | Placeholder entry in DB. |
document/quiz | Concurrent creation of study materials. | Bulk creation via workspaceWorker. |
youtube | Search and integration of relevant media. | searchVideos tool call. |
Sources: src/app/generate/page.tsx:15-25, src/app/api/workspaces/autogen/route.ts:550-650
Autogen Concurrency Flow
The diagram represents the parallelized nature of the autogen system, where metadata distillation, content generation, and OCR processing happen concurrently to minimize latency in a collaborative environment.
Sources: src/app/api/workspaces/autogen/route.ts:360-390, src/app/api/workspaces/autogen/route.ts:500-550
Summary
Realtime collaboration in ThinkEx is achieved through an event-sourced architecture that synchronizes workspace state, user actions, and AI context. By recording every interaction as a versioned event, the system provides a reliable environment for multi-user participation, comprehensive version control, and context-aware AI assistance. The use of streaming APIs and parallel background workers ensures that complex collaborative tasks, such as workspace autogeneration, remain responsive and transparent to all participants.