State Management & Data Fetching

Vata utilizes a hybrid architecture for state management and data fetching, combining local client-side state with an asynchronous server-state model for its SQLite databases. The application differentiates between UI-centric state, managed by Zustand, and database-synchronized state, managed by TanStack Query (React Query).

The system is designed to handle a local-first desktop environment where data resides in two distinct SQLite databases: a System DB for app-level metadata and a Tree DB for specific genealogical project data. This structure ensures that genealogical research remains portable and isolated per project.

Sources: CLAUDE.md:29, README.md:25-30, README.md:73-77

State Management Architecture

The project employs two primary libraries for state management, each serving a specific scope:

Sources: CLAUDE.md:43, README.md:29

Data Flow Overview

Data flow in Vata moves from the React UI through TanStack Query hooks, which interact with orchestration Managers. These managers call the DB layer, which utilizes Tauri IPC to execute SQL commands in the Rust-backed SQLite environment.

The flow ensures separation of concerns between UI presentation and data persistence.
Sources: README.md:65-71

Asynchronous Data Fetching (TanStack Query)

TanStack Query is used to manage the lifecycle of data fetched from the SQLite databases. This includes handling loading states, error boundaries, and cache invalidation.

Query Keys

The application uses a centralized queryKeys constant to maintain consistency across the app, ensuring that invalidations target the correct data subsets.

export const queryKeys = {
  trees: ['trees'] as const,
  individuals: (treeId: string) => ['trees', treeId, 'individuals'] as const,
  families: (treeId: string) => ['trees', treeId, 'families'] as const,
};

Sources: src/lib/query-keys.ts:1-5, src/components/trees/import-gedcom-modal.tsx:29

Mutations and Cache Invalidation

When data is modified (e.g., importing a GEDCOM file), useMutation is utilized to handle the asynchronous operation. Upon success, the queryClient is used to invalidate relevant queries, triggering a UI refresh.

Database Connection Management

Vata implements a two-database design managed through src/db/connection.ts. Connection state (references to open databases) is held in module-level variables.

Connection State Variables

• systemDb: Reference to the system.db holding app-level metadata.
• treeDb: Reference to the currently active project database.
• currentTreePath: String path of the currently open tree.

Sources: src/db/connection.ts:6-10

Database Lifecycle

The application context determines which database is active. The "outside picker" uses the System DB, while the "inside shell" opens a specific Tree DB based on the route.

The openTreeDb function closes any existing tree connection before opening a new one to ensure single-tree isolation.
Sources: CLAUDE.md:32-40, src/db/connection.ts:316-321

Connection Parameters (PRAGMAs)

Every database connection is initialized with specific performance and safety settings:

• journal_mode = WAL: Write-Ahead Logging for concurrency.
• foreign_keys = ON: Enforces relational integrity.
• busy_timeout = 5000: Prevents immediate locking errors.
• temp_store = MEMORY: Accelerates temporary operations.

Sources: src/db/connection.ts:12-19

Conclusion

State management in Vata is strategically split between UI state and persistent data. By utilizing TanStack Query as an intermediary between the React UI and the SQLite databases, the application achieves robust data synchronization while maintaining the performance benefits of a local-first desktop architecture. The two-database design further ensures that global app settings and individual project data remain distinct and properly scoped.