Persistence Layer (IndexedDB)

Relevant source files

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

• app/lib/persistence/db.ts
• app/lib/persistence/useChatHistory.ts
• app/lib/persistence/fileSystem.ts
• app/lib/stores/workbench.ts
• app/components/chat/Chat.client.tsx

The Persistence Layer in Bolt provides a robust mechanism for storing and retrieving chat histories and project states. It primarily utilizes IndexedDB for browser-based storage, while also integrating with the local file system to provide a hybrid synchronization model. This ensures that user progress, including chat messages and artifact descriptions, remains persistent across sessions even when the application is refreshed or closed.

Sources: app/lib/persistence/db.ts, app/lib/persistence/useChatHistory.ts:18-24

Architecture Overview

The persistence architecture is designed around a dual-storage strategy. IndexedDB acts as the primary database within the browser environment, while the fileSystem.ts module manages secondary persistence to a user-selected local directory. The useChatHistory hook serves as the orchestrator, managing the initialization and state transitions between these storage layers.

Data Flow for Chat Initialization

The following diagram illustrates how the system attempts to resolve and load chat history when a user enters a chat session.

Database Schema

The IndexedDB database is named boltHistory and uses versioning to manage structural changes. It contains a single object store named chats.

Object Store: chats

The chats store uses the id field as its primary key.

Field	Type	Constraint	Description
id	string	Primary Key, Unique Index	Unique identifier for the chat session.
urlId	string	Unique Index	Human-readable ID used in the application URL.
description	string	Optional	A brief title or summary of the chat.
messages	Message[]	Required	Array of chat messages (user and assistant).
timestamp	string	Required	ISO string representing the last update.

Sources: app/lib/persistence/db.ts:11-23, app/lib/persistence/useChatHistory.ts:10-16

Core Components and Functions

Database Management (db.ts)

This module handles direct interactions with the IndexedDB API.

• openDatabase(): Initializes the boltHistory database and creates the chats store with relevant indices (id, urlId). Sources: app/lib/persistence/db.ts:8-28
• setMessages(...): Saves a ChatHistoryItem to IndexedDB. If a local directory is selected, it simultaneously triggers a write to the file system. Sources: app/lib/persistence/db.ts:46-77
• getMessages(db, id): A retrieval wrapper that prioritizes the file system. If local files are missing, it falls back to querying IndexedDB by id or urlId. Sources: app/lib/persistence/db.ts:79-104
• getNextId(db): Determines the next numeric ID by finding the highest current ID in the store and incrementing it. Sources: app/lib/persistence/db.ts:128-140

React Integration (useChatHistory.ts)

The useChatHistory hook manages the lifecycle of persistence within React components.

• Ready State: Monitors whether the database is open and initial history has been loaded. Sources: app/lib/persistence/useChatHistory.ts:31-33
• Persistence Toggle: Controlled by the VITE_DISABLE_PERSISTENCE environment variable. Sources: app/lib/persistence/useChatHistory.ts:18
• Synchronization: The storeMessageHistory function ensures that every new message is persisted to both IndexedDB and the local .boltnew.json file. Sources: app/lib/persistence/useChatHistory.ts:91-125

File System Synchronization

The system integrates IndexedDB with the browser's File System Access API.

External File Change Monitoring

The persistence layer also accounts for changes made to files outside the browser environment (e.g., in a local editor). The WorkbenchStore initiates a periodic check (default 30 seconds) that leverages the persistence layer to detect delta changes between the local directory and the internal state.

• checkForFileChanges(): Scans the selectedDirectoryHandle for file updates. Sources: app/lib/persistence/fileSystem.ts:167-203
• syncExternalChanges(): Compares external changes against the EditorStore documents and synchronizes them if they differ. Sources: app/lib/stores/workbench.ts:128-142

Summary

The Persistence Layer (IndexedDB) serves as the backbone of Bolt's state management, ensuring that chat interactions and generated code are never lost. By combining the speed of IndexedDB with the flexibility of local file system access, it provides a seamless developer experience that bridges the gap between browser-based AI and local development workflows. Sources: app/lib/persistence/db.ts, app/lib/persistence/fileSystem.ts, app/lib/persistence/useChatHistory.ts