How Tolaria's Internal Architecture Works: A Deep Dive into the Rust-React Data Flow

Tolaria is a Tauri-powered desktop application that implements a three-tier data architecture—Filesystem, Cache, and React State—where the filesystem always serves as the single source of truth and all UI mutations write to disk before updating in-memory state.

Tolaria is an open-source note-taking application built with Tauri v2 and React with TypeScript. Understanding Tolaria's internal architecture reveals how it maintains data consistency across crashes while delivering fast performance on large vaults through intelligent caching and git-aware incremental updates.

The Three-Layer Data Model

Tolaria organizes all data into three distinct layers that cascade from persistent storage to the UI. This design ensures that your .md files remain the ultimate authority while the application remains responsive.

Filesystem as Source of Truth

At the base of the architecture sits the Filesystem layer—standard Markdown files on disk with YAML frontmatter. All vault-level configuration, note content, and metadata reside here. Unlike many electron-based note apps that use proprietary databases, Tolaria keeps your data in plain text files that remain accessible to standard Unix tools and git workflows.

The filesystem never gets polluted with application data. As implemented in refactoringhq/tolaria, the vault directory contains only your notes, while the application stores its ephemeral data elsewhere.

The Cache Layer

Sitting between the filesystem and the UI is the Cache layer located at ~/.laputa/cache/. This is a fast-startup index generated by the Rust command scan_vault_cached() defined in [src-tauri/src/vault/cache.rs](https://github.com/refactoringhq/tolaria/blob/main/src-tauri/src/vault/cache.rs).

The cache serves two critical functions:

• Fast cold starts: The app can display your vault instantly without scanning thousands of files
• Git-aware invalidation: The cache stores a hash of the vault path and the current Git commit SHA. When cache.rs detects a HEAD change, it runs a git diff to re-parse only altered files rather than performing a full filesystem walk

If the cache is missing, corrupt, or the git diff cannot be trusted, the system falls back to a full vault scan and rebuilds the index automatically.

React State Management

The top layer is React State, specifically an in-memory array of VaultEntry[] objects managed by the useVaultLoader hook. When the application starts, useVaultLoader (imported in [src/App.tsx](https://github.com/refactoringhq/tolaria/blob/main/src/App.tsx)) reads the cache or triggers a full scan to populate the React state.

This state is ephemeral—if the app crashes, no data is lost because the React state is purely a read-only projection of the filesystem, rebuilt on every launch.

Data Flow and Disk-First Consistency

The most important architectural invariant in Tolaria is the "disk-first" rule: any UI mutation must write to the filesystem via a Tauri IPC command before updating the React state.

// Pattern used in src/utils/vault-dialog.ts
async function updateNoteContent(notePath: string, content: string) {
  // Step 1: Write to filesystem via Tauri IPC
  await invoke('save_note_content', { path: notePath, content });
  
  // Step 2: Only update React state after successful write
  setVaultEntries(prev => prev.map(entry => 
    entry.path === notePath ? { ...entry, content } : entry
  ));
}

This approach guarantees consistency even if a write fails or the application crashes mid-operation. The frontend code in [src/utils/vault-dialog.ts](https://github.com/refactoringhq/tolaria/blob/main/src/utils/vault-dialog.ts) provides UI wrappers around these Tauri IPC calls, ensuring every save operation follows this protocol.

Frontend Architecture and Layout

The React frontend renders a four-panel layout defined in [src/App.tsx](https://github.com/refactoringhq/tolaria/blob/main/src/App.tsx):

1. Sidebar: Navigation and vault selection
2. Note List / Pulse View: Search results and recent notes
3. Editor: Markdown editing surface
4. Right Panel: Inspector, Table of Contents, and AI Agent interface

The application bootstrap sequence looks like this:

// src/App.tsx simplified
import { useVaultLoader } from './hooks/useVaultLoader';

function App() {
  // Loads vault from cache or triggers full scan
  const { vaultEntries, isLoading } = useVaultLoader(resolvedVaultPath);
  
  return (
    <div className="four-panel-layout">
      {/* Panel components consuming vaultEntries */}
    </div>
  );
}

Multi-window support is implemented via the helper openNoteInNewWindow found in [src/utils/openNoteWindow.ts](https://github.com/refactoringhq/tolaria/blob/main/src/utils/openNoteWindow.ts), allowing users to pop out individual notes into separate Tauri windows while maintaining the same data flow architecture.

AI Agent Integration

Tolaria includes a built-in AI panel that communicates with local CLI agents (Claude, Codex, OpenCode, Pi, Gemini). The integration follows a strict separation between context building and command execution:

Context Building

The frontend constructs a JSON snapshot of the current note environment in [src/utils/ai-context.ts](https://github.com/refactoringhq/tolaria/blob/main/src/utils/ai-context.ts):

// src/utils/ai-context.ts
export function buildAIContext(activeNote: Note, vaultEntries: VaultEntry[]) {
  return {
    currentNote: activeNote,
    backlinks: findBacklinks(activeNote.path, vaultEntries),
    surroundingContext: getNeighborNotes(activeNote),
    timestamp: new Date().toISOString()
  };
}

Backend Execution

This context is passed to the Rust command stream_ai_agent defined in src-tauri/src/ai_agents.rs. The Rust backend selects the appropriate agent adapter and spawns the CLI subprocess, streaming responses back to the frontend.

MCP Server Bridge

Tool calls from the AI agent—such as search_notes or edit_note_frontmatter—are routed through the MCP server at [mcp-server/index.js](https://github.com/refactoringhq/tolaria/blob/main/mcp-server/index.js). This bridge allows the AI to manipulate the vault while respecting the same disk-first consistency rules as the UI.

Cache Invalidation and Incremental Updates

The cache implementation in src-tauri/src/vault/cache.rs uses a sophisticated invalidation strategy to keep large vaults responsive:

1. Commit-based versioning: Each cache entry is tagged with the current Git HEAD
2. Differential updates: When the commit changes, the system runs git diff to identify modified files
3. Selective re-parsing: Only changed files are re-parsed and merged into the existing cache index
4. Fallback to full scan: If git is not available or the diff is unreliable, the system gracefully degrades to a full vault scan

This incremental approach ensures that opening a vault with thousands of notes remains instantaneous, even after pulling updates from a remote repository.

Summary

• Tolaria's internal architecture centers on a three-tier data model: Filesystem (source of truth), Cache (fast startup), and React State (UI projection)
• Disk-first consistency requires all mutations to write via Tauri IPC to the filesystem before updating React state, preventing data loss on crashes
• Git-aware caching in src-tauri/src/vault/cache.rs uses commit SHAs and incremental diffs to maintain fast performance on large vaults
• AI integration separates context building (TypeScript frontend) from command execution (Rust backend) via the MCP server bridge
• Multi-window support extends the architecture to secondary windows while maintaining the same data flow guarantees

Frequently Asked Questions

How does Tolaria handle data consistency if the app crashes?

Tolaria enforces a disk-first write policy where all mutations must successfully write to the filesystem via Tauri IPC commands before the React state is updated. Because the cache is rebuilt from the filesystem on every startup, crashing after a failed write leaves your data in a consistent state on disk, with the React state simply regenerated from the last successful write.

Where does Tolaria store its cache and why is it outside the vault directory?

The cache is stored in ~/.laputa/cache/ (or platform equivalent) rather than inside the vault directory. This separation ensures your git repository contains only your notes without application artifacts, prevents cache files from appearing in version control, and allows the cache to be safely deleted or rebuilt without touching your actual data.

How does Tolaria's AI integration maintain security and privacy?

Tolaria communicates with AI agents through local CLI tools rather than cloud APIs, and all context building happens locally in [src/utils/ai-context.ts](https://github.com/refactoringhq/tolaria/blob/main/src/utils/ai-context.ts). The MCP server bridge in mcp-server/index.js provides a controlled interface for AI tool calls, ensuring the agent can only perform vault operations through validated Rust commands that follow the same disk-first consistency rules as the UI.

What triggers a full vault rescan versus an incremental cache update?

A full rescan occurs when the cache is missing, corrupt, or when the Git HEAD changes in a way that makes the diff unreliable. Incremental updates happen automatically when src-tauri/src/vault/cache.rs detects a new commit SHA and can successfully run git diff to identify only the changed files, allowing the system to update the cache without re-parsing the entire vault.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}