Architecture Overview

Relevant source files

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

• package.json
• CONTRIBUTING.md
• app/lib/stores/workbench.ts
• app/lib/runtime/message-parser.ts
• app/components/workbench/Workbench.client.tsx
• app/components/chat/BaseChat.tsx
• app/lib/stores/editor.ts
• app/root.tsx
• vite.config.ts

Bolt is an AI-powered development environment that enables users to prompt, run, edit, and deploy full-stack web applications directly in the browser. It leverages a combination of AI models (Claude Sonnet 3.5), browser-based execution environments (WebContainers), and a modern web stack (Remix, Vite, and NanoStores) to provide a seamless development experience without requiring local installations or remote virtual machines.

The architecture is centered around a "streaming agent" model where LLM responses are parsed in real-time to execute file system operations, run shell commands, and manage a live development environment.

Sources: CONTRIBUTING.md:4-22, README.md:10-25

Core Technology Stack

The project utilizes a specific set of technologies to achieve high-performance browser-based development:

Component	Technology	Description
Framework	Remix Run	Full-stack web framework for React.
Runtime	WebContainer API	Browser-based Node.js runtime for running servers and tools.
State Management	NanoStores	Tiny, framework-agnostic state management library.
Editor	CodeMirror 6	Extensible code editor for the web.
AI Integration	Vercel AI SDK	Integration with Anthropic's Claude Sonnet 3.5.
Styling	UnoCSS & SCSS	Atomic CSS engine and Sass for complex styling.
Deployment	Cloudflare Pages/Workers	Distributed serverless infrastructure.

Sources: package.json:44-80, CONTRIBUTING.md:28-48, app/root.tsx:1-20

System Architecture

The system is split between a React-based UI layer and a robust background state management layer that interacts with the WebContainer runtime.

Data Flow and Component Relationship

The following diagram illustrates how user input travels through the AI model to eventually trigger actions in the browser sandbox.

State Management (NanoStores)

The application uses nanostores to manage global state, allowing for reactive updates across the Workbench, Editor, and Chat components.

WorkbenchStore

The WorkbenchStore acts as the central orchestrator. It manages the visibility of the workbench, the current view (code vs. preview), and coordinates between the file system and the editor.

• Artifacts: Tracks AI-generated tasks (ArtifactState) and their associated ActionRunner.
• File Management: Tracks unsavedFiles using a Set<string> and manages EditorDocument states.
• Terminal: Controls the lifecycle and visibility of the integrated xterm.js terminal.

Sources: app/lib/stores/workbench.ts:25-60, app/lib/stores/editor.ts:10-25

EditorStore

The EditorStore specifically handles the state of open documents within CodeMirror. It maps file paths to EditorDocument objects containing content, scroll positions, and binary flags.

Sources: app/lib/stores/editor.ts:30-70

Runtime & Parsing

One of the most critical systems in Bolt is the StreamingMessageParser, which processes the live stream from the LLM.

Artifact and Action Parsing

The parser looks for custom XML-like tags within the AI's markdown response to trigger side effects.

Tag	Attributes	Purpose
<boltArtifact>	id, title	Groups a set of related development actions.
<boltAction>	type="file", filePath	Instructs the system to create or update a specific file.
<boltAction>	type="shell"	Instructs the system to execute a command in the terminal.

Components and UI

The UI is divided into two primary zones: the Chat and the Workbench.

BaseChat Component

The BaseChat component handles user input, prompt enhancement, and message rendering. It supports "Enhance Prompt" functionality via AI and provides example prompts to guide the user.
Sources: app/components/chat/BaseChat.tsx:40-100

Workbench Component

The Workbench is a client-side component that slides in from the right when development starts. It provides a tabbed interface for:

• EditorPanel: Displays the FileTree and the CodeMirrorEditor.
• Preview: An iframe that renders the application running inside the WebContainer.
  Sources: app/components/workbench/Workbench.client.tsx:87-160

Build and Environment Configuration

The project is optimized for Cloudflare and Vite.

• Vite Configuration: Uses nodePolyfills for path and buffer to support Node.js tools in the browser. It includes a specific chrome129IssuePlugin to handle module loading issues in specific browser versions during local development.
• Cloudflare Integration: Deployment is managed via wrangler, targeting esnext and utilizing nodejs_compat flags.

Sources: vite.config.ts:10-40, wrangler.toml:1-5, package.json:10-25

Conclusion

Bolt's architecture represents a shift toward "AI-native" development tools. By decoupling the execution environment (WebContainer) from the IDE UI and using a reactive streaming parser, it allows an LLM to act as a primary agent capable of performing complex file system and server operations entirely within the user's browser session.