Tree Management
Relevant source files
The following files were used as context for generating this wiki page:
Tree Management encompasses the lifecycle, storage, and metadata orchestration of genealogical family trees within the Vata application. The system follows a local-first architecture where each tree is treated as a standalone SQLite database, while a centralized system database manages app-level metadata and the list of available trees.
Sources: README.md:10-15, CLAUDE.md:38-42, src/db/connection.ts:316-320
Architecture and Database Design
The application utilizes a Two-Database Design to separate global application state from specific genealogical data.
- System DB (
system.db): Stores app-level metadata, including the list of trees, their file paths, and general app settings. - Tree DB (
<tree-name>.db): A portable SQLite file containing all genealogical data (individuals, families, events, places, sources) for a single family tree.
Sources: CLAUDE.md:44-51, src/db/connection.ts:316-368
System Database Schema
The trees table in system.db tracks the inventory of local family trees.
| Field | Type | Description |
|---|---|---|
id | INTEGER | Primary key (formatted as string ID in UI) |
name | TEXT | User-defined name of the tree |
path | TEXT | Unique filesystem path to the tree's directory |
description | TEXT | Optional user-provided notes about the tree |
individual_count | INTEGER | Cached count of individuals in the tree |
family_count | INTEGER | Cached count of families in the tree |
last_opened_at | TEXT | ISO timestamp of the last time the tree was accessed |
created_at | TEXT | ISO timestamp of tree creation |
Sources: src/db/system/trees.ts:5-16, src/db/connection.ts:316-330
Connection Management
The connection layer handles the initialization and lifecycle of these databases. It applies specific SQLite PRAGMAs (WAL mode, Foreign Keys ON, Busy Timeout 5000ms) to ensure data integrity and performance.
The diagram shows the sequence of database initialization from application launch to opening a specific tree.
Sources: src/db/connection.ts:10-18, src/db/connection.ts:340-355
Tree Lifecycle Operations
The TreeManager class serves as the primary orchestrator for tree lifecycle events, coordinating between the UI components, the System DB, and the filesystem.
Creation and Path Resolution
When a new tree is created, the system generates a slug from the name. To prevent file collisions while allowing non-unique tree names, the system resolve an available path by appending numeric suffixes (e.g., slug-2, slug-3) if the directory already exists.
Sources: src/managers/TreeManager.ts:24-52
Opening and Closing
Opening a tree involves multiple steps: loading metadata from the system DB, establishing a connection to the tree-specific SQLite file, updating the "last opened" timestamp, and updating the global application state via useAppStore.
This diagram illustrates the multi-layered process of activating a family tree.
Sources: src/managers/TreeManager.ts:59-71, src/db/connection.ts:357-375
UI Components
The tree management interface is primarily hosted on the Home page and uses Radix UI primitives for interactions.
Component Summary
| Component | Purpose | Key Functionality |
|---|---|---|
NewTreeModal | Creation | Supports "Blank tree" and "From me" (coming soon) modes. |
EditTreeModal | Modification | Allows renaming and updating the tree description. |
DeleteTreeModal | Destruction | Destructive action requiring name confirmation; offers GEDCOM export before deletion. |
DownloadTreeModal | Export | Exports tree data to GEDCOM 5.5.1 format. |
ImportGedcomModal | Import | Scans and imports .ged files into a new local database. |
Sources: src/pages/Home.tsx:180-215, src/components/trees/new-tree-modal.tsx:15-25, src/components/trees/delete-tree-modal.tsx:55-70
Statistical Tracking
The system maintains cached counts of individuals and families in the system database. These are updated via TreeManager.updateStats, which queries the active tree database and writes the results back to system.db.
Sources: src/managers/TreeManager.ts:81-86, src/db/system/trees.ts:98-115
Data Models
Tree metadata is standardized across the application using TypeScript interfaces to ensure consistency between the raw database rows and the UI.
// src/types/database.ts:7-17
export interface Tree {
id: string;
name: string;
path: string;
description: string | null;
individualCount: number;
familyCount: number;
lastOpenedAt: string | null;
createdAt: string;
updatedAt: string;
}
Sources: src/types/database.ts:7-17, src/db/system/trees.ts:19-31
Summary
Tree Management in Vata provides a robust, local-first framework for handling multiple genealogy projects. By separating project-specific data into individual SQLite files while maintaining a centralized management layer, the system ensures both data portability and efficient application-wide project tracking. Key operations like path resolution, statistics caching, and confirmation-guarded deletion provide a safe and performant user experience for managing complex genealogical datasets.