Getting Started & Setup
Relevant source files
The following files were used as context for generating this wiki page:
Vata is a local-first, desktop-based genealogy application designed to manage family trees with data privacy at its core. It leverages a modern tech stack combining a Rust-based shell (Tauri) with a React frontend and SQLite for local data persistence. The project is structured to ensure that all genealogical data remains on the user's machine, requiring no cloud accounts or subscriptions.
Sources: README.md:1-12, CLAUDE.md:21-25
Development Environment Setup
Prerequisites
Before setting up the project, ensure the following tools are installed on your system:
| Tool | Version / Requirement | Source |
|---|---|---|
| Node.js | >= 20 | README.md:38 |
| pnpm | >= 9 | README.md:39 |
| Rust | Stable | README.md:40 |
| Tauri System Deps | Platform-specific dependencies | README.md:41 |
| gh CLI | Authenticated (for project scripts) | scripts/setup-gh-project.sh:12 |
Local Installation
Follow these steps to initialize the development environment:
# Clone the repository
git clone https://github.com/vata-apps/vata-app.git
cd vata-app
# Install dependencies
pnpm install
# Start development environment
pnpm tauri:dev
Sources: README.md:45-54
Project Initialization & Automation
The application automatically initializes its database environment upon the first launch. A system.db file is created to store app-level metadata, such as the list of managed trees and global settings.
Sources: README.md:56, src/db/connection.ts:311-325
GitHub Project Setup
For contributors, the project includes a bootstrapping script scripts/setup-gh-project.sh to reconcile GitHub labels and project structures. This script ensures the repository follows the taxonomy for genealogy domains like individuals, families, and GEDCOM standards.
The diagram shows the automated workflow for setting up the GitHub repository environment for development and tracking.
Sources: scripts/setup-gh-project.sh:1-125
Architecture & Data Flow
Vata uses a layered architecture where the frontend React application communicates with a SQLite database through a Tauri IPC bridge.
This diagram illustrates the data flow from the user interface down to the physical SQLite storage.
Sources: README.md:72-78
Two-Database Design
The system manages two distinct types of SQLite databases simultaneously to separate global application state from specific family tree data.
| Database | Filename | Purpose |
|---|---|---|
| System DB | system.db | Tree list, last opened metadata, app settings. |
| Tree DB | <tree-name>.db | Persons, names, events, and family relationships. |
Sources: CLAUDE.md:31-38, src/db/connection.ts:311-350
Common Development Commands
The package.json defines several scripts for development, testing, and building the application.
| Command | Description |
|---|---|
pnpm tauri:dev | Launches the full desktop app in development mode with HMR. |
pnpm build | Performs TypeScript checks and generates the Vite production build. |
pnpm test | Runs the Vitest suite in watch mode. |
pnpm lint | Executes ESLint checks across the codebase. |
pnpm format | Formats source files using Prettier. |
Sources: package.json:30-43, CLAUDE.md:8-19
Database Connection Management
The connection logic in src/db/connection.ts handles the lifecycle of these databases, applying critical PRAGMAs for performance and integrity.
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:13-20
Conclusion
Setting up Vata requires a standard Rust and Node.js environment. The application's local-first architecture is reflected in its dual-database setup and its reliance on Tauri for cross-platform desktop capabilities. Developers can quickly get started by installing dependencies and running the tauri:dev command, which automates the initial system database creation.