High-Level Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• README.md
• package.json
• app/lib/stores/workbench.ts
• app/lib/runtime/message-parser.ts
• app/lib/persistence/fileSystem.ts
• app/root.tsx
• vite.config.ts

Bolt is an open-source AI-powered software development tool designed to allow users to prompt, run, edit, and deploy full-stack web applications directly within the browser. The architecture leverages a combination of modern web technologies to create a seamless developer experience without requiring local installations or remote virtual machines.

The system is built as a Remix application deployed on Cloudflare Pages, utilizing the Vercel AI SDK for LLM integration (specifically Anthropic's Claude 3.5 Sonnet) and the StackBlitz WebContainer API to provide a sandboxed Node.js environment in the browser.

Sources: CONTRIBUTING.md:10-25, README.md:15-30

Core System Components

The architecture is divided into three primary layers: the User Interface (built with Remix and React), the State Management layer (using Nanostores), and the Runtime/Infrastructure layer (WebContainers and File System Access API).

Architecture Overview Diagram

This diagram illustrates the high-level relationship between the user's browser, the AI provider, and the underlying sandbox environment.

State Management and Workbench

The WorkbenchStore serves as the central orchestrator for the application's development environment. It manages multiple sub-stores that handle specific aspects of the IDE-like functionality.

Component	Description
WorkbenchStore	Orchestrates files, previews, editor, and terminal stores.
FilesStore	Manages the in-memory representation of the project files within the WebContainer.
EditorStore	Tracks open documents, selections, and scroll positions in CodeMirror.
TerminalStore	Manages terminal instances and their visibility.
Artifacts	Tracks "Artifacts" generated by the AI, which contain executable actions.

Sources: app/lib/stores/workbench.ts:32-75

Workbench Lifecycle

The Workbench synchronizes changes between the internal WebContainer filesystem and the user's local directory using a periodic check mechanism.

AI Integration and Message Parsing

Bolt uses a specialized StreamingMessageParser to handle incoming streams from the AI. The parser identifies custom XML-like tags (<boltArtifact> and <boltAction>) to extract structured instructions from the AI's natural language response.

Execution Flow of AI Actions

When the AI suggests a change, it wraps instructions in "Artifacts" and "Actions". The parser detects these and triggers callbacks that the Workbench uses to update the environment.

1. Artifact Detection: The parser identifies <boltArtifact> with attributes like title and id.
2. Action Detection: Inside artifacts, <boltAction> tags specify the type (e.g., shell or file).
3. Callback Trigger: The StreamingMessageParser triggers onActionOpen and onActionClose callbacks.
4. Action Runner: The ActionRunner executes the shell commands or writes files directly into the WebContainer.

Sources: app/lib/runtime/message-parser.ts:60-120, app/lib/stores/workbench.ts:225-260

Persistence Layer

Bolt implements the File System Access API to allow users to sync their browser-based projects with a local directory on their machine.

Function	File Path	Description
selectDirectory	app/lib/persistence/fileSystem.ts	Opens the browser's directory picker and stores the handle.
writeFile	app/lib/persistence/fileSystem.ts	Navigates the FileSystemDirectoryHandle to write content to a local file.
checkForFileChanges	app/lib/persistence/fileSystem.ts	Traverses the local directory to detect modifications made outside the browser.

Sources: app/lib/persistence/fileSystem.ts:57-110

Development and Build Configuration

The project utilizes Vite for development and building, with specific configurations for Cloudflare compatibility and Node.js polyfills.

Vite Configuration*: Includes nodePolyfills for path and buffer to support Node-dependent libraries in the browser.

• Wrangler: Configured to deploy to Cloudflare Pages with nodejs_compat flags enabled.
• Styling: Uses UnoCSS for atomic CSS and Scss for component-specific styles.

Sources: vite.config.ts:10-30, wrangler.toml:1-5, package.json:15-30

Conclusion

The High-Level Architecture of Bolt demonstrates a sophisticated integration of browser-based runtimes (WebContainers) and AI streaming. By offloading the compute-intensive development environment to the client's browser and using a structured parsing system for AI responses, Bolt achieves a high-performance, collaborative development environment that bridges the gap between local and cloud-based IDEs.