Local Database (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/stores/workbench.ts
• app/root.tsx
• app/components/chat/BaseChat.tsx

The Local Database system in Bolt provides a client-side persistence layer using the browser's IndexedDB API. Its primary purpose is to store chat history, messages, and metadata locally, ensuring that user interactions and AI-generated content are preserved across sessions without requiring a centralized backend database for every interaction.

This system manages the lifecycle of chat records, including creation, retrieval, updates, and deletion. It integrates closely with the application's state management and routing to provide a seamless experience where chats can be resumed or referenced via unique identifiers.
Sources: app/lib/persistence/db.ts:1-10, app/lib/persistence/useChatHistory.ts:18-25

Database Architecture and Schema

The system initializes a specific IndexedDB database named boltHistory. It utilizes a versioned schema to manage the object stores required for application data.

Database Initialization

The database is opened using the openDatabase function. During the onupgradeneeded event, the system ensures the existence of the necessary object stores and indices.
Sources: app/lib/persistence/db.ts:7-24

The diagram shows the initialization flow of the local IndexedDB instance.
Sources: app/lib/persistence/db.ts:10-33

Data Model: chats Object Store

The chats store is the primary repository for application data. It uses id as the primary key (keyPath).

Field	Type	Description
id	string	Primary unique identifier for the chat.
urlId	string	Unique identifier used for URL-based navigation.
description	string	A human-readable title or description of the chat.
messages	Message[]	An array of AI and User messages associated with the session.
timestamp	string	ISO string representing the last update time.

Sources: app/lib/persistence/db.ts:17-21, app/lib/persistence/useChatHistory.ts:9-15

Data Access Operations

The system provides an asynchronous API for interacting with the IndexedDB instance, wrapping standard IDBRequest objects in Promises.

Retrieval Methods

Data can be retrieved by primary ID or by the secondary urlId index. The getMessages function acts as a fallback wrapper, attempting retrieval by ID first and then by URL ID.
Sources: app/lib/persistence/db.ts:56-82

Function	Method	Target
getAll	store.getAll()	Retrieves all chat history items.
getMessagesById	store.get(id)	Retrieves a specific chat by primary key.
getMessagesByUrlId	index('urlId').get(id)	Retrieves a chat using the indexed URL ID.

Sources: app/lib/persistence/db.ts:36-44, app/lib/persistence/db.ts:60-82

Persistence and Updates

The setMessages function handles the "upsert" logic using store.put(). It captures the current state of messages and automatically attaches a new timestamp.
Sources: app/lib/persistence/db.ts:46-58

The sequence shows how the application triggers a save operation through the history hook.
Sources: app/lib/persistence/useChatHistory.ts:62-84, app/lib/persistence/db.ts:46-58

Integration with Application Logic

The database logic is primarily consumed by the useChatHistory hook, which synchronizes the local database state with the React application's lifecycle.

Chat Initialization and Persistence Control

Persistence can be globally disabled via the VITE_DISABLE_PERSISTENCE environment variable. If disabled, the db instance remains undefined, and the application falls back to volatile memory-only state.
Sources: app/lib/persistence/useChatHistory.ts:18-20

ID Generation and URL Mapping

The system includes utilities to manage identifiers:

• getNextId: Scans existing keys to determine the next numeric identifier.
• getUrlId: Ensures uniqueness of URL-friendly IDs by appending increments (e.g., id-2) if a conflict is detected.
  Sources: app/lib/persistence/db.ts:93-118

Lifecycle Flow

1. Mount: On component mount, useChatHistory checks for a mixedId in the URL. If present, it queries the DB.
2. State Sync: If data is found, it populates initialMessages and application-wide atoms like chatId.
3. Automatic Save: When messages are updated, the hook persists the new state and updates the URL if a new session was just created.
   Sources: app/lib/persistence/useChatHistory.ts:33-58, app/lib/persistence/useChatHistory.ts:62-80

Summary

The Local Database system provides a robust mechanism for client-side chat retention. By leveraging IndexedDB and React Hooks, the project achieves persistent state without a traditional server-side database, allowing users to maintain their AI development sessions entirely within their browser.
Sources: app/lib/persistence/db.ts, app/lib/persistence/useChatHistory.ts