Introduction to Vata
Relevant source files
The following files were used as context for generating this wiki page:
Vata is a local-first desktop application designed for managing genealogical family trees. The application prioritizes data sovereignty, ensuring all information remains on the user's machine without the need for accounts, cloud services, or subscriptions. It supports standard genealogical practices, including GEDCOM 5.5.1 interoperability and complex relationship mapping.
Sources: README.md:1-12, CONTEXT.md:1-5
The project is built using a modern tech stack centered on Tauri and React. It utilizes a two-database architecture to separate application-level metadata from specific family tree data, providing a robust and portable solution for genealogical research.
Sources: README.md:21-30, CLAUDE.md:27-38
Core Architecture and Tech Stack
Vata follows a layered architectural pattern that bridges a high-level React UI with a low-level SQLite database via Tauri's Inter-Process Communication (IPC).
Architectural Layers
The data flow moves from the UI components down through hooks and managers to the database layer:
- UI Layer: React pages and components.
- Hook Layer: TanStack Query for data fetching, caching, and mutations.
- Manager Layer: Orchestration of business logic, validation, and transactions.
- DB Layer: SQLite CRUD operations and type mapping.
- Shell: Tauri IPC communicating with the SQLite backend.
Sources: README.md:55-61, CLAUDE.md:37-45
Technology Summary
| Layer | Technology |
|---|---|
| Shell/Backend | Tauri 2 (Rust) |
| Frontend | React 18 + TypeScript 5 |
| Database | SQLite (via @tauri-apps/plugin-sql) |
| State Management | Zustand (client) + TanStack Query (server) |
| Routing | TanStack Router (file-based) |
| Styling | Radix Themes |
| Sources: README.md:21-30, CLAUDE.md:31-35, package.json:54-68 |
The following diagram illustrates the relationship between the different architectural layers:
Sources: README.md:55-61
Database Design
Vata employs a two-database design to manage information efficiently. This separation ensures that application settings and the list of available trees are independent of the genealogical data within a specific tree.
Database Types
- System DB (
system.db): Stores app-level metadata, including the list of family trees and general application settings. - Tree DB (
<tree-name>.db): Contains all genealogical data for a specific family tree, such as individuals, families, events, and places. Each tree is stored in its own portable database file.
Sources: README.md:63-68, CLAUDE.md:37-45
Database Connection Lifecycle
Connection management is handled in src/db/connection.ts. The application initializes the System DB on launch and opens/closes specific Tree DBs as the user navigates between the "picker" (home) and the "inside shell" (tree view).
Data Domain and Entities
The application manages several key genealogical entities, following conventions established by the GEDCOM 5.5.1 standard.
Key Entities
- Individual: A person in the tree. While referred to as "Individual" in the database and code, the UI uses the label "Person".
- Family: A union record linking individuals in roles such as husband, wife, and child.
- Event: A dated occurrence (birth, marriage, death) attached to individuals or families.
- Source & Citation: A Source is a document (e.g., a census); a Citation is a specific reference to a Source (e.g., a specific page).
- Place: Hierarchical locations attached to events.
Sources: CONTEXT.md:7-40
Entity ID Convention
Database primary keys are integers, but the UI and TypeScript types use formatted string IDs for clarity:
| Prefix | Entity | Example |
|---|---|---|
| I | Individual | I-0001 |
| F | Family | F-0002 |
| E | Event | E-0003 |
| P | Place | P-0004 |
| S | Source | S-0005 |
| Sources: CLAUDE.md:65-74 |
Entity Relationships
The following Entity-Relationship diagram shows how core genealogical data is structured within the Tree DB:
Sources: CONTEXT.md:42-51, src/db/connection.ts:31-230
Development and Configuration
Vata is configured as a cross-platform desktop application using Tauri.
Directory Structure
src/: React frontend source code.db/: Database logic for system and tree databases.gedcom-parser/: Logic for importing/exporting GEDCOM files.managers/: Business logic orchestration.routes/: File-based routing definitions.
src-tauri/: Rust backend and Tauri configuration.docs/: Architecture Decision Records (ADRs) and project specifications.
Sources: README.md:88-103
Build and Runtime Configuration
The tauri.conf.json file defines the application's identity and window properties. It specifies sqlite:system.db as a preloaded plugin and sets the security Content Security Policy (CSP).
Sources: src-tauri/tauri.conf.json:1-35
Key Development Commands
pnpm tauri:dev # Runs the desktop app in development mode
pnpm test # Runs Vitest in watch mode
pnpm build # Performs TypeScript check and Vite build
Sources: README.md:44-53, CLAUDE.md:14-25
Conclusion
Vata provides a robust, local-first environment for genealogical research, leveraging Tauri's ability to combine web technologies with a native SQLite backend. Its architecture is strictly divided between global application management and individual tree data, ensuring user privacy and data portability. Through adherence to GEDCOM standards and a clear entity relationship model, it provides a professional-grade tool for managing complex family histories.