Product Terminology & Glossary
Relevant source files
The following files were used as context for generating this wiki page:
This page defines the core genealogical and technical terminology used within the Vata application. It serves as a single source of truth for the language used in the codebase, database schema, and user interface. Vata is a local-first desktop editor compatible with the GEDCOM 5.5.1 standard.
The glossary is divided into domain-specific entities (such as Individuals and Families) and system-level concepts (such as Tree Databases and Entity IDs). Understanding these terms is critical for maintaining consistency across the different layers of the application, from the SQLite schema to the React frontend.
Core Genealogical Entities
Vata utilizes a specific set of entities to represent a family tree. These entities align closely with the GEDCOM standard but often use different labels for technical implementation versus user-facing UI.
Tree
A Tree represents a complete genealogical dataset for a single research project. Each tree is stored as an independent SQLite database file.
- Avoid: Project, File, Database.
- Sources: CONTEXT.md:6-8, CLAUDE.md:65-66
Individual (Person)
An Individual is a person within a tree. This term is used in the database schema (individuals table), code, and types. In the user-facing UI, the label Person or People is preferred.
- Avoid: Profile, Record.
- Sources: CONTEXT.md:10-12, CLAUDE.md:83-85
Family
A Family is a union record that links an optional husband, an optional wife, and zero or more children. It exists independently of any specific event like a marriage ceremony.
- Avoid: Marriage, Couple, Union, Household.
- Sources: CONTEXT.md:18-20, src/db/connection.ts:66-73
Event
An Event is a dated and placed occurrence recorded in a tree, such as a birth, death, or marriage. Events have participants (Individuals or Families) assigned to specific roles like "principal" or "witness."
- Avoid: Fact, Milestone, Attribute.
- Sources: CONTEXT.md:26-28, src/db/connection.ts:168-185
Domain Relationship Overview
The following diagram illustrates how core entities relate to one another within the system.
This diagram shows the high-level relationships between a Tree and its constituent genealogical entities.
Sources: CONTEXT.md:43-52, src/db/connection.ts:25-240
Evidence & Documentation Terms
Vata distinguishes between the physical sources of information and the specific references used to support genealogical claims.
| Term | Definition | Avoid |
|---|---|---|
| Source | A piece of documentary evidence supporting a fact (e.g., a parish register, census, or certificate). | Document, Record |
| Citation | A specific reference into a Source (e.g., a specific page or transcription). Citations are linked to entities like Individuals or Events. | Reference, Source citation |
| Repository | An institution holding sources, such as an archive, library, or church. | Archive, Library |
| Quality | An assessment of reliability for a piece of evidence (Primary, Secondary, Questionable, Unreliable). | Confidence, Reliability |
Sources: CONTEXT.md:34-41, src/db/connection.ts:242-299
Technical Infrastructure Terms
These terms describe the system's architecture and the conventions used by developers.
Two-Database Design
Vata maintains two distinct types of SQLite databases simultaneously:
- System DB (
system.db): Stores app-level metadata, including the list of trees and application settings. - Tree DB (
<tree-name>.db): Stores all genealogical data for a specific tree.
- Sources: CLAUDE.md:61-71, src/db/connection.ts:8-12
Entity ID Convention
To bridge the gap between integer primary keys in SQLite and string-based IDs in the UI, Vata uses formatted string IDs.
| 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:94-106, src/managers/SourceWorkspaceManager.ts:192-194
GEDCOM
GEDCOM (Genealogical Data Communication) is the standard text-based interchange format (version 5.5.1) that Vata uses for importing and exporting data. The system uses a specialized parser to convert these text files into database records.
Workspace Orchestration
The application uses Managers to coordinate complex workflows. A key example is the SourceWorkspaceManager.
Template
A Template is a definition used to orchestrate the creation of multiple entities at once from a single source document (e.g., a marriage record). It defines "slots" for individuals and rules for creating families.
The flow of the SourceWorkspaceManager orchestration when processing a template.
Sources: src/managers/SourceWorkspaceManager.ts:140-190
Slot
A Slot represents a role within a template (e.g., "Husband" or "Witness"). It can be filled by an existing individual or a new one created during the process.
Summary
The Product Terminology & Glossary provides a unified language for the Vata project. By strictly separating user-facing terms (like "Person") from technical terms (like "Individual") and enforcing clear distinctions between concepts (like "Source" versus "Citation"), the project ensures architectural clarity and technical accuracy across its local-first, GEDCOM-compliant ecosystem.