Architecture Overview

Relevant source files

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

• CLAUDE.md
• README.md
• CONTEXT.md
• src/db/connection.ts
• src/db/trees/sources.ts
• src-tauri/tauri.conf.json

Vata is a local-first, cross-platform desktop application designed for managing genealogical family trees. Built with Tauri and React, it prioritizes data privacy by storing all information locally on the user's machine using SQLite. The application is designed to be GEDCOM 5.5.1 compatible, allowing for seamless interoperability with other genealogy software.

The architecture follows a layered approach where the React frontend communicates through a management layer to a specialized database layer, which in turn interacts with the Rust-based Tauri shell to execute persistent storage operations.

Sources: README.md:3-13, README.md:39-45, CLAUDE.md:65-68

Tech Stack and System Components

The application leverages a modern web-stack encapsulated within a native shell.

Layer	Technology
Shell	Tauri 2 (Rust)
Frontend	React 18, TypeScript 5, Vite
Database	SQLite via @tauri-apps/plugin-sql
State Management	Zustand (Client-side), TanStack Query (Server-side/Async data)
Routing	TanStack Router (File-based)
Styling	Radix Themes

Sources: README.md:15-24, CLAUDE.md:65-68

The following diagram illustrates the high-level data flow from the UI to the persistence layer:

Two-Database Design

A core architectural feature is the separation of app-level settings and tree-specific data into two distinct SQLite databases.

System Database (system.db)

This database stores global application metadata. It is opened and initialized on first launch and manages the list of known family trees and user preferences.
Sources: CLAUDE.md:70-78, src/db/connection.ts:316-335

Tree Database (<tree-name>.db)

Each family tree is encapsulated in its own .db file. This contains all genealogical entities like individuals, families, events, and sources. The application is designed as a "single-tree-at-a-time" editor; the tree database is opened when a user enters a specific tree context and closed upon exit.
Sources: CLAUDE.md:60-63, CLAUDE.md:70-78, src/db/connection.ts:337-353

Data Domain and Schema

The data model is built around standard genealogical entities defined in the GEDCOM specification.

Core Entities

• Individual: A person in the tree, containing gender and life status.
• Name: Naming records linked to Individuals. One individual can have multiple names (e.g., birth, married), with one flagged as primary.
• Family: Union records linking optional spouses (husband/wife) and children.
• Event: Dated and placed occurrences (Birth, Marriage, Death, etc.).
• Source & Citation: Documentary evidence. A Citation is a specific reference into a Source (e.g., a specific page).
• Place: Hierarchical geographic locations.

Sources: CONTEXT.md:6-33, src/db/connection.ts:18-120

Entity Relationship Diagram

The relationships between these entities are strictly managed to maintain genealogical integrity:

Database Layer Implementation

The database layer in src/db/ follows a specific pattern to ensure type safety and clean separation between the database and the UI.

1. Raw Types: Interfaces representing snake_case SQLite columns (e.g., RawSource).
2. Domain Types: camelCase TypeScript types used by the rest of the application.
3. Mapping: Pure functions (e.g., mapToSource) that convert raw database rows into domain objects.
4. CRUD Functions: Exported async functions that perform SQL operations using explicit column lists (no SELECT *).

Sources: CLAUDE.md:89-96, src/db/trees/sources.ts:10-45

Entity ID Convention

To distinguish between different entity types in the UI and code, Vata uses a prefixed string ID system. Internally, the database uses INTEGER PRIMARY KEY AUTOINCREMENT.

Prefix	Entity	Example
I	Individual	I-0001
F	Family	F-0002
E	Event	E-0003
S	Source	S-0004

Sources: CLAUDE.md:80-87, src/db/trees/sources.ts:31-32

Connection Management

Connection management is centralized in src/db/connection.ts. Every connection is configured with specific SQLite PRAGMAs for performance and reliability, including WAL (Write-Ahead Logging) mode and foreign key enforcement.

async function applyConnectionPragmas(db: Database): Promise<void> {
  await db.execute('PRAGMA journal_mode = WAL');
  await db.execute('PRAGMA synchronous = NORMAL');
  await db.execute('PRAGMA foreign_keys = ON');
  await db.execute('PRAGMA busy_timeout = 5000');
}

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

The application lifecycle manages these connections through two main contexts:

• Outside Picker (/): Interacts with the System DB to list trees.
• Inside Shell (/tree/$treeId): The openTreeDb(treePath) function is called to load the specific genealogical data.

Sources: CLAUDE.md:60-63, src/db/connection.ts:337-353

Summary

Vata's architecture is a robust, local-first system designed for scalability and interoperability. By utilizing a two-database design and a strict layered approach to data management, it ensures that complex genealogical relationships are handled efficiently while keeping user data private and portable. The use of Tauri provides a native desktop experience with the flexibility of modern web technologies.