Workspaces API
Relevant source files
The following files were used as context for generating this wiki page:
The Workspaces API serves as the central orchestration layer for managing user environments within ThinkEx. It handles the lifecycle of workspaces—including creation, metadata updates, deletion, and retrieval—while integrating with an event-sourcing backend to maintain state consistency across distributed clients.
The API supports both standard CRUD operations and advanced AI-driven features, such as automated workspace generation from natural language prompts and intelligent metadata extraction (titles, icons, and colors). It ensures multi-tenant security through strict ownership and collaborator permission checks.
Sources: src/app/api/workspaces/route.ts, src/app/api/workspaces/autogen/route.ts
Core API Endpoints
The API is structured around RESTful principles for standard management, with specialized routes for AI augmentation.
Workspace Management
| Method | Endpoint | Description |
|---|---|---|
GET | /api/workspaces | Lists all workspaces owned by or shared with the authenticated user. |
POST | /api/workspaces | Creates a new workspace using a template or custom initial state. |
GET | /api/workspaces/[id] | Retrieves metadata and replayed state for a specific workspace. |
PATCH | /api/workspaces/[id] | Updates workspace metadata (name, description, icon, color, privacy). |
DELETE | /api/workspaces/[id] | Permanently deletes a workspace and its associated event history. |
Sources: src/app/api/workspaces/route.ts:12-258, src/app/api/workspaces/[id]/route.ts:14-142
AI and Automation
| Method | Endpoint | Description |
|---|---|---|
POST | /api/workspaces/autogen | Streams the creation of a workspace, including AI-distilled summaries and items. |
POST | /api/workspaces/generate-title | Generates a concise title, icon, and color from a user prompt. |
Sources: src/app/api/workspaces/autogen/route.ts:167-526, src/app/api/workspaces/generate-title/route.ts:17-86
Architecture and Data Flow
The Workspaces API employs an event-sourcing architecture. Rather than storing a static snapshot of the workspace content in the primary workspaces table, content changes are recorded as a sequence of events via the append_workspace_event PostgreSQL function.
Workspace Creation Flow
When a workspace is created, the system initializes metadata and then appends an initial event (either WORKSPACE_CREATED or WORKSPACE_SNAPSHOT) to establish the starting state.
The system includes retry logic for slug collisions, ensuring unique URLs by appending counters if a generated slug already exists.
Sources: src/app/api/workspaces/route.ts:117-251, src/app/api/workspaces/[id]/route.ts:79-114
State Retrieval and Replay
Retrieving a workspace requires "replaying" events to reconstruct the current AgentState. The GET /api/workspaces/[id] endpoint fetches the base metadata from the database and calls loadWorkspaceState to aggregate all historical events into a single state object.
AI Autogen System
The autogen feature is a sophisticated multi-phase pipeline that uses Google Gemini models to transform a user prompt and optional attachments into a fully-functional workspace.
Distillation Pipeline
- Search Phase: Determines if the prompt requires real-time web information.
- Distillation Phase: Processes prompts, files (PDFs/Images), and links to extract a summary and metadata.
- Content Generation: Produces a study document, a quiz with multiple questions, and retrieves relevant YouTube videos.
- Bulk Creation: Appends all generated items to the workspace in a single transaction.
Streaming Protocol
The autogen API uses a streaming NDJSON response to provide real-time feedback to the client. This allows the UI to show progress indicators for various stages of generation.
| Event Type | Data Payload |
|---|---|
phase | The current stage (e.g., "understanding"). |
metadata | The generated title, icon, and color. |
partial | Partial text/JSON updates for the document or quiz. |
toolCall | Information about background tools like webSearch. |
complete | The final workspace ID, slug, and name. |
Sources: src/app/api/workspaces/autogen/route.ts:365-375
Workspace Worker Operations
The workspaceWorker is the internal utility responsible for executing specific state-mutating actions. It enforces concurrency control and handles the complexities of different item types.
Supported Actions and Logic
- Edit: Handles targeted string replacement or full rewrites for documents, quizzes, and flashcards. It includes a
parseJsonWithRepairutility to ensure that AI-edited JSON structures remain valid. - UpdateFlashcard/UpdateQuiz: Specifically handles appending new questions or cards to existing items without overwriting previous content.
- OCR Integration: The
updatePdfContentandupdateImageContentactions are used to cache extracted text from assets once OCR processing is complete.
Sources: src/lib/ai/workers/workspace-worker.ts:182-588
Version Conflict Resolution
The worker uses the workspace version to detect and resolve conflicts. If two users edit the same workspace simultaneously, the append_workspace_event function detects the mismatch. For certain operations like create, the worker implements retry logic to automatically resolve version conflicts.
Sources: src/lib/ai/workers/workspace-worker.ts:251-309
Summary
The Workspaces API provides a robust foundation for the ThinkEx platform, combining traditional relational storage for metadata with an event-sourced model for dynamic content. Its tight integration with AI services allows for seamless transition from a simple prompt to a populated workspace, while internal workers ensure that all modifications—whether manual or automated—are recorded consistently and securely.