Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
ThinkEx is a visual thinking environment designed to consolidate AI reasoning and personal knowledge into a persistent, spatial workspace. Unlike traditional chat-based AI tools, ThinkEx emphasizes user-controlled context, allowing users to organize PDFs, YouTube videos, and notes on a canvas where AI can interact with specific, manually selected items.
The project is built as a production-grade Next.js application utilizing a modern TypeScript stack. It leverages PostgreSQL for persistence, Drizzle ORM for database interactions, and TanStack Query for state management. AI capabilities are primarily powered by Google's Gemini models, integrated via the AI SDK.
Sources: README.md:1-40, README.md:65-75
Core Tech Stack
The application follows a full-stack Next.js architecture with the following primary components:
| Component | Technology | Description |
|---|---|---|
| Framework | Next.js | React-based framework for server-side rendering and API routes. |
| Database | PostgreSQL | Relational database for storing workspaces, items, and users. |
| ORM | Drizzle ORM | TypeScript ORM for type-safe database queries. |
| State Management | Zustand & TanStack Query | Client-side state and server-state synchronization. |
| Auth | Better Auth | Authentication framework with Google OAuth support. |
| Styling | Tailwind CSS & Shadcn UI | Utility-first CSS and accessible UI components. |
| AI Integration | Vercel AI SDK & Google AI | Streamlined interface for Generative AI and tool-calling. |
Sources: README.md:65-75, setup.sh:1-50
Workspace Context System
A critical architectural feature of ThinkEx is the explicit management of AI context. The system uses a specialized formatting utility to convert workspace items (PDFs, documents, quizzes) into a structured prompt context for the AI assistant.
Context Generation Flow
The assistant does not receive all workspace data at once. Instead, it receives:
- Workspace FS: A high-level overview of paths and metadata for all items.
- Selected Cards: Full content for items explicitly selected or "currently viewed" by the user.
The system prioritizes items marked as (currently viewing) and specific PDF pages (activePage=N) to ensure the AI's reasoning aligns with the user's visual focus.
Sources: src/lib/utils/format-workspace-context.ts:55-100, src/lib/utils/format-workspace-context.ts:325-360
AI Autogen System
The Workspace Autogen system is a multi-phase pipeline that creates structured knowledge environments from simple prompts, files, or links. It utilizes a streaming architecture to provide real-time feedback to the user during the generation process.
Autogen Pipeline Phases
- Phase 0: Workspace Initialization: Immediately creates a placeholder workspace and begins OCR processing for any uploaded PDFs or images in parallel.
- Phase 1: Search & Distillation: Determines if web search is needed via a "Flash-lite" model, fetches search results, and distills the input into a workspace title, icon, and content summary.
- Phase 2: Content Generation: Generates a structured study document and a quiz (5-10 questions) concurrently with YouTube video searching.
- Phase 3: Bulk Creation: Persists all generated items to the database.
Data Modeling & Storage
ThinkEx supports flexible storage backends and a structured item system.
Storage Options
The application can be configured via environment variables to use different storage strategies:
- Local File Storage: Files are stored in a local
./uploadsdirectory (default for self-hosting). - Supabase Storage: Cloud-based storage using Supabase buckets.
Workspace Item Types
The Item data structure represents various types of content on the spatial canvas:
- PDF: Includes OCR-extracted markdown pages and metadata like
activePage. - Document: Raw markdown content.
- Flashcard: JSON-based decks with front/back markdown.
- Quiz: JSON-structured questions with session progress tracking.
- YouTube: Video URLs with transcript-backed context capabilities.
Sources: README.md:145-165, src/lib/utils/format-workspace-context.ts:10-50, src/app/api/workspaces/autogen/route.ts:30-50
Deployment and Environment
The application is container-ready and includes an interactive setup script (setup.sh) for local development.
| Category | Key Variables | Purpose |
|---|---|---|
| Database | DATABASE_URL | Connection string for PostgreSQL. |
| Auth | BETTER_AUTH_SECRET, GOOGLE_CLIENT_ID | Security and OAuth configuration. |
| AI | GOOGLE_GENERATIVE_AI_API_KEY | Access to Gemini models. |
| Storage | STORAGE_TYPE, SUPABASE_URL | Configures local vs. cloud storage. |
Sources: README.md:100-140, setup.sh:65-100
Conclusion
The ThinkEx architecture is optimized for a "visual thinking" flow where AI is a collaborator with access to explicit, user-defined context. By leveraging a streaming Next.js backend and a multi-phase AI generation pipeline, the system provides a responsive environment for building persistent knowledge. The separation of workspace metadata from full item content allows for efficient scaling of context as workspaces grow in complexity.
Sources: README.md:30-60, src/lib/utils/format-workspace-context.ts:60-80