Skip to content

Data Model and Storage

Core in-memory model

The central entity is ChatMessage: role, content, timestamp, optional thinking text, image, audio URL, latency metrics, tool calls, and tool results. UserPreferences describes the selected LLM variant, STT/TTS settings, language, thinking/tools flags, and barge-in behavior.

erDiagram
  %%{init: {"theme":"base","themeVariables":{"primaryColor":"#1e293b","primaryTextColor":"#f8fafc","primaryBorderColor":"#38bdf8","lineColor":"#64748b","attributeBackgroundColor":"#1e293b","attributeTextColor":"#f8fafc"}}}%%
  USER_PREFERENCES ||--o{ CHAT_MESSAGE : configures_session
  CHAT_MESSAGE ||--o{ TOOL_CALL : contains
  CHAT_MESSAGE ||--o{ TOOL_RESULT : records
  CHAT_MESSAGE {
    string role
    string content
    string thinking
    string image
    string audioUrl
    number createdAt
  }
  USER_PREFERENCES {
    string variantId
    string sttModelId
    string ttsEngine
    boolean sttEnabled
    boolean ttsEnabled
  }
  TOOL_CALL {
    string name
    string arguments
  }
  TOOL_RESULT {
    string name
    string content
    string error
  }

This is an application model rather than a database schema; entities are held in React state.

Browser storage

  • localStorage: setup and UI preferences.
  • IndexedDB/cache APIs: model assets, according to provider behavior documented in the README.
  • OPFS/browser cache: Piper voice assets.
  • Memory and object URLs: PCM playback and message audio.

No server-side export, durable conversation database, or synchronization mechanism is present. Data consistency is therefore straightforward within one tab, but reloads discard the conversation.

Lifecycle concerns

The code explicitly revokes message audio URLs and unloads models during reset/unmount. Model switching unloads stale engine/model combinations to reduce memory pressure. Large binary assets are the dominant storage and performance concern.

Preference schema

The persisted blueprint includes the selected model variant, STT model and enabled flag, TTS engine/voice/language and enabled flag, thinking mode, experimental tools, Hindi typing, barge-in, and configured state. Preferences are intentionally user-local; they are not an account profile.

Memory ownership

Resource Owner Release path
MediaStream tracks useVoiceAgent stopListening
AudioContext/worklet useVoiceAgent disconnect and close
STT worker workerRef terminate on reset/unmount
LLM engine provider hooks unload on switch/reset/unmount
TTS engine useTTS stop/reset/unload
Message audio URL ChatMessage revokeMessageAudioUrls

This ownership table is central to correctness because browser memory pressure is user-visible and large models are not garbage-collected promptly if engine references remain active.