Individuals & Families Management

Relevant source files

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

• src/db/trees/individuals.ts
• src/db/trees/families.test.ts
• src/managers/SourceWorkspaceManager.ts
• src/pages/IndividualsPage.tsx
• src/types/database.ts
• src/db/trees/debug.ts
• CLAUDE.md

The Individuals & Families Management system is the core of the Vata application, responsible for handling the genealogical data structure of family trees. It encompasses the creation, storage, and relationship mapping of persons (Individuals) and their unions (Families). This system is designed to be GEDCOM 5.5.1 compatible, ensuring that data integrity is maintained for interoperability with other genealogical software.

Sources: README.md, CONTEXT.md

Architecture and Data Models

The system follows a layered architecture where React components interact with Managers, which in turn use the DB layer to perform SQLite operations. Data models are defined using TypeScript interfaces that map raw database rows (snake_case) to public domain types (camelCase).

Entity ID Convention

Entities are identified by a formatted string ID using specific prefixes:

• I-: Individual (e.g., I-0001)
• F-: Family (e.g., F-0002)

Sources: CLAUDE.md:85-94, src/lib/entityId.ts

Core Data Structures

Entity	Description	Key Fields
Individual	Represents a person in the tree.	id, gender (M/F/U), isLiving, notes
Name	A naming record for an individual.	givenNames, surname, isPrimary, type
Family	A union record linking spouses and children.	id, notes
FamilyMember	A junction entity linking individuals to families.	role (husband/wife/child), pedigree

Sources: src/types/database.ts:31-155, CONTEXT.md

Individual Management

Individual management involves handling person records and their associated names. An individual is uniquely identified and can have multiple names (e.g., birth name, married name), though exactly one is flagged as primary.

Logical Relationship

The following diagram illustrates how Individuals relate to Names and Families:

This diagram shows the relationship between core genealogical entities.
Sources: src/db/trees/debug.ts:162-210, src/types/database.ts:200-215

Key Functions

• createIndividual(input: CreateIndividualInput): Persists a new person record. Defaults gender to 'U' (Unknown) if not provided. Sources: src/db/trees/individuals.ts:88-103
• searchIndividuals(query: string): Performs a JOIN between individuals and names to find matches across given names and surnames. Sources: src/db/trees/individuals.ts:143-157
• parseName(fullName: string): Utility to split a full name string into givenNames and a surname (the last word). Sources: src/managers/SourceWorkspaceManager.ts:55-71

Family Management

Families in Vata represent the union record linking an optional husband, optional wife, and zero or more children. The ceremony (Marriage Event) is distinct from the Family record itself.

Family Relationship Rules

The system enforces rules for creating parent-child and couple relationships:

1. Couple: Requires both spouse slots to be filled.
2. Parent-Child: Requires the child slot and at least one parent slot to be filled.

Sources: src/managers/SourceWorkspaceManager.ts:163-205

Data Flow for Family Creation

When creating records from a template (e.g., a marriage record), the SourceWorkspaceManager orchestrates the creation of all related entities.

This flow shows the orchestration logic used to transform source data into tree entities.
Sources: src/managers/SourceWorkspaceManager.ts:211-274

UI Implementation: Individuals Page

The IndividualsPage component renders a full-width table of all persons in the open tree. It uses the EntityTable component and provides features for sorting and navigation.

Table Columns

Column	Logic / Source
Name	Formatted as surnameFirst. Includes an Avatar with initials.
Sex	Translated value based on person.gender.
Birth	Extracted year from person.birthEvent.dateSort.
Death	Extracted year from person.deathEvent.dateSort (if not living).

Sources: src/pages/IndividualsPage.tsx:55-103

Implementation Detail: Initials Generation

function initialsOf(name: Name | null): string {
  if (!name) return '?';
  const given = name.givenNames?.trim().split(/\s+/)[0]?.charAt(0) ?? '';
  const surname = name.surname?.trim().charAt(0) ?? '';
  const initials = (given + surname).toUpperCase();
  if (initials) return initials;
  const nickname = name.nickname?.trim().charAt(0);
  return nickname ? nickname.toUpperCase() : '?';
}

Sources: src/pages/IndividualsPage.tsx:32-41

Conclusion

The Individuals & Families Management system provides a robust framework for managing complex genealogical relationships. By separating the core entity (Individual/Family) from its attributes (Names) and occurrences (Events), the system achieves GEDCOM compatibility while maintaining a clean, queryable data structure. This modular approach allows for flexible data entry via templates and consistent display throughout the user interface.