Background Workflows System
Relevant source files
The following files were used as context for generating this wiki page:
The Background Workflows System in ThinkEx is a robust infrastructure designed to handle asynchronous, long-running tasks such as Optical Character Recognition (OCR), automated workspace generation, and content extraction. It leverages a combination of AI-driven distillation, worker processes, and external tool execution to transform raw user input—such as PDFs, images, and web links—into structured, interactive workspace elements.
The system is primarily orchestrated through a series of phases, starting from initial request ingestion to final state updates in the PostgreSQL database. This ensures that heavy processing (e.g., extracting text from a 100-page PDF) does not block the user interface, providing real-time progress updates via Server-Sent Events (SSE) and specialized workers.
Sources: src/app/api/workspaces/autogen/route.ts:251-260, src/app/generate/page.tsx:14-22
Architecture and Orchestration
The system follows a multi-phase execution model, particularly evident in the autogen module. When a user requests a new workspace, the system triggers a series of parallel and sequential background workflows.
Workflow Execution Phases
The generation workflow is divided into logical stages to optimize performance and user feedback:
| Phase | Description | Key Components |
|---|---|---|
| Phase 0: Initialization | Creates the workspace shell and initializes asset items in the database. | workspaces table, workspaceWorker |
| Phase 1: Search & Distillation | Decides if a web search is needed and distills input content into metadata. | runSearchPhase, runDistillationAgent |
| Phase 2: Content Generation | Generates documents and quizzes using AI based on distilled summaries. | documentQuizFn, google("gemini-2.5-flash") |
| Phase 3: Bulk Ingestion | Finalizes the workspace state by inserting all generated content items. | workspaceWorker("bulkCreate") |
Sources: src/app/api/workspaces/autogen/route.ts:316-350, src/app/api/workspaces/autogen/route.ts:483-500, src/app/api/workspaces/autogen/route.ts:586-595
Data Flow for Asset Processing
The background system utilizes a "dispatch" pattern for heavy media processing. For instance, when PDFs or images are uploaded during workspace creation, the system triggers the ocrDispatchWorkflow immediately in Phase 0 to start extraction in parallel with content generation.
The diagram above illustrates how the system branches into parallel asset processing while simultaneously proceeding with AI-driven content synthesis.
Sources: src/app/api/workspaces/autogen/route.ts:403-440, src/app/api/workspaces/autogen/route.ts:483-500
AI Worker Modules
Workflows are supported by specialized "Workers" that encapsulate specific AI logic. These workers are isolated from the main request/response cycle to maintain modularity.
Text Selection Worker
The textSelectionWorker handles transformations on user-selected text. It supports actions like summarization, explanation, and translation, returning only the transformed content to the UI.
Sources: src/lib/ai/workers/text-selection-worker.ts:9-15
Search and Grounding Tools
The executeWebSearch function acts as a background tool for retrieving real-time data. It uses Google search grounding to provide verified sources, which are then resolved from redirect URLs (like Vertex AI search redirects) to direct links.
Sources: src/lib/ai/tools/web-search.ts:98-115
Asset Processing and OCR
Asset processing is a critical background workflow that ensures media files are searchable and readable by the AI assistant.
OCR Status Management
Items containing media (PDFs and Images) track their background processing state through a set of status flags stored in the database.
| Status | Meaning |
|---|---|
processing | The background OCR job has been dispatched and is currently running. |
failed | The OCR process encountered an error (e.g., file size, format, or timeout). |
success (Implied) | Content is extracted and populated in ocrPages. |
Sources: src/lib/utils/format-workspace-context.ts:430-440, src/app/api/workspaces/autogen/route.ts:445-455
Content Extraction Flow
When OCR finishes, the system updates the ocrPages field. The formatOcrPagesAsMarkdown utility then transforms this raw data into structured markdown, replacing table placeholders with actual content for the AI to consume.
The sequence diagram shows the transition from background data extraction to the final formatting required for the AI context.
Sources: src/lib/utils/format-workspace-context.ts:369-385, src/lib/utils/format-workspace-context.ts:410-425
Real-time Progress Tracking
The system communicates background workflow progress to the frontend using an NDJSON (Newline Delimited JSON) stream. This allows the UI to update labels dynamically as the background tasks complete.
Stream Event Types
The background system emits the following events during the autogen workflow:
phase: Indicates a major stage shift (e.g., "understanding").toolCall: Notifies the user when a background search or URL fetch is starting.partial: Streams partial AI outputs for the workspace title or document title.progress: Signals completion of specific components (e.g., "quiz", "youtube").complete: Final event providing the workspace slug for redirection.
Sources: src/app/api/workspaces/autogen/route.ts:640-650, src/app/generate/page.tsx:85-110
Summary
The Background Workflows System is the engine behind ThinkEx's ability to handle complex, multi-modal content. By decoupling media processing (OCR), external data retrieval (Web Search), and creative generation (AI Distillation) into a phased, event-driven architecture, the project maintains a responsive user experience while performing computationally expensive tasks in the background. This architecture ensures that workspace content is not just aggregated but structured and grounded in extracted facts.