Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Bolt is an AI-powered development platform designed to prompt, run, edit, and deploy full-stack web applications directly in the browser. The architecture leverages the StackBlitz WebContainer API to execute Node.js environments locally within the browser tab, combined with the Vercel AI SDK for integration with Large Language Models (LLMs) like Claude 3.5 Sonnet.
The system is built as a full-stack Remix application, optimized for deployment on edge platforms such as Cloudflare Pages and Vercel. It bridges the gap between AI-generated code and a functional development environment by providing a virtualized filesystem, package manager, and terminal.
Sources: README.md:9-16, README.md:27-33
Core System Components
The application architecture is divided into three primary layers: the AI Orchestration layer, the Workbench/Runtime layer, and the Persistence layer.
1. Application Shell (Remix & Vite)
The project utilizes Remix with Vite for server-side rendering (SSR) and client-side hydration. The server entry point manages security headers essential for WebContainers, such as Cross-Origin Isolation.
| Component | Technology | Description |
|---|---|---|
| Framework | Remix Run | Handles routing and SSR. |
| Build Tool | Vite | Manages bundling and local dev server. |
| Deployment | Cloudflare / Vercel | Targeted for serverless/edge environments. |
| Styling | UnoCSS | Atomic CSS engine for UI components. |
Sources: vite.config.ts:16-35, app/entry.server.tsx:75-76, app/root.tsx:14-25
2. Workbench & WebContainer Runtime
The Workbench is the central hub for user interaction, managing the state of the code editor, previews, and the terminal. It communicates directly with the WebContainer API to execute the AI's instructions.
The diagram shows the relationship between the React UI, the state management (Workbench Store), and the sandboxed WebContainer environment.
Sources: app/lib/stores/workbench.ts:31-40, README.md:27-33
3. State Management (Nanostores)
State is managed using nanostores for reactivity across the application. The WorkbenchStore aggregates several sub-stores to manage distinct parts of the developer experience.
- FilesStore: Tracks the state of the virtual filesystem.
- EditorStore: Manages document contents, selections, and scroll positions for CodeMirror.
- TerminalStore: Handles terminal attachments and resizing.
- PreviewsStore: Manages the lifecycle of internal application previews.
Sources: app/lib/stores/workbench.ts:32-35, app/lib/stores/editor.ts:12-25
Data Flow: From Prompt to File
The system follows a specific flow when the AI generates code changes. The StreamingMessageParser identifies custom XML-like tags (boltArtifact and boltAction) within the LLM stream to trigger filesystem updates or terminal commands.
This flow illustrates how AI responses are parsed into actionable commands that update both the browser's virtual environment and the user's local directory.
Sources: app/lib/runtime/message-parser.spec.ts:110-125, app/lib/stores/workbench.ts:193-210, app/lib/persistence/fileSystem.ts:133-145
Persistence Strategy
The application implements a dual-persistence strategy to ensure code safety and history:
- IndexedDB: Stores chat history and messages through the
persistence/dbmodule. - Native File System API: Allows users to sync their browser-based workspace with a directory on their local computer.
Local File System Sync
The fileSystem.ts module uses showDirectoryPicker to gain access to a local directory. It synchronizes changes between the WebContainer's virtual memory and the user's physical disk.
| Function | File | Purpose |
|---|---|---|
selectDirectory | fileSystem.ts | Prompts user to pick a folder and stores the handle. |
writeFile | fileSystem.ts | Navigates directory handles to write content to disk. |
checkForFileChanges | fileSystem.ts | Traverses local directory to detect external edits. |
syncExternalChanges | workbench.ts | Updates the Workbench and Editor when local files change. |
Sources: app/lib/persistence/fileSystem.ts:70-100, app/lib/persistence/fileSystem.ts:192-210, app/lib/stores/workbench.ts:167-180
Security and Cross-Origin Isolation
Because WebContainers rely on SharedArrayBuffer, the architecture requires strict security headers. These are enforced at the server entry point and development configuration.
// app/entry.server.tsx:75-76
responseHeaders.set('Cross-Origin-Embedder-Policy', 'require-corp');
responseHeaders.set('Cross-Origin-Opener-Policy', 'same-origin');
These headers enable Cross-Origin Isolation, allowing the browser to run a multi-threaded Node.js environment safely.
Sources: app/entry.server.tsx:75-76, README.md:144-152, vite.config.ts:1-15
Summary
The Bolt architecture is a sophisticated integration of edge-ready web frameworks (Remix), local runtime virtualization (WebContainers), and reactive state management (Nanostores). By parsing AI streams into discrete filesystem and terminal actions, it creates a seamless loop between natural language prompting and full-stack software development within a secure, isolated browser environment.