Entity ID System

Relevant source files

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

• CLAUDE.md
• src/lib/entityId.test.ts
• src/db/connection.ts
• src/db/trees/citations.ts
• src/db/trees/sources.ts
• src/db/trees/files.ts
• src/db/trees/places.ts

The Entity ID System in Vata serves as a bridge between the persistent storage layer and the user interface. While the underlying SQLite database utilizes standard INTEGER primary keys for performance and referential integrity, the TypeScript domain model and UI use formatted string identifiers (e.g., I-0001). This approach aligns with GEDCOM 5.5.1 cross-reference standards and provides human-readable identifiers throughout the application.

Sources: CLAUDE.md:74-85, src/db/connection.ts:31-35

Core ID Conventions

Vata enforces a strict prefixing and padding convention for different genealogical entities. IDs are composed of a single-letter prefix, a hyphen, and a zero-padded number (minimum 4 digits).

Entity Prefixes

The following prefixes are used to categorize identifiers:

Prefix	Entity Type	Example	Database Table
I	Individual	I-0001	individuals
F	Family	F-0042	families
E	Event	E-0123	events
P	Place	P-9999	places
S	Source	S-0005	sources
R	Repository	R-0001	repositories

Sources: CLAUDE.md:78-83, src/lib/entityId.test.ts:32-39

Padding Logic

IDs are zero-padded to a minimum length of four digits. If the numerical ID exceeds four digits, the full number is preserved without truncation.

• 1 becomes 0001
• 42 becomes 0042
• 12345 becomes 12345

Sources: src/lib/entityId.test.ts:6-22

Conversion Architecture

The system operates primarily at the boundaries of the database layer. Every database operation involves a conversion step handled by specialized utility functions.

Data Flow Diagram

The following diagram illustrates how identifiers move between the UI and the database during a typical write and read cycle.

Utility Functions

Conversion logic is centralized in src/lib/entityId.ts (tested via src/lib/entityId.test.ts):

• formatEntityId(prefix: string, id: number): Combines a prefix and an integer into a formatted string.
• parseEntityId(formattedId: string): Extracts the integer from a formatted string; throws an error if the format is invalid or non-numeric.
• getEntityPrefix(formattedId: string): Extracts only the prefix (e.g., "I") from a full ID string.

Sources: src/lib/entityId.test.ts:5-75

Database Implementation

In the SQLite schema, primary keys are defined as INTEGER PRIMARY KEY AUTOINCREMENT. This ensures unique, incremental values that the Entity ID system then formats.

Mapping Patterns

Each database access module (found in src/db/trees/) follows a mapping pattern to handle these ID conversions:

function mapToSource(raw: RawSource): Source {
  return {
    id: formatEntityId('S', raw.id),
    repositoryId: raw.repository_id !== null ? formatEntityId('R', raw.repository_id) : null,
    // ... other fields
  };
}

Sources: src/db/trees/sources.ts:31-35, src/db/trees/places.ts:46-50

Polymorphic Entity Handling

Certain tables, such as citation_links, reference multiple entity types. The system uses specific helper functions to determine which prefix to apply based on the entity_type column.

Citation and Referral Logic

A key feature of the Entity ID system is its use in junction tables and search operations.

Cross-Reference Tables

Many-to-many relationships often store the raw integer but return formatted IDs to the application:

• Source Files: Associates Sources (S) with Files. getSourcesByFileId returns an array of formatted "S-XXXX" strings.
• Citation Links: Connects Citations to Individuals, Families, Events, or Places.

Junction Table	Purpose	ID Handling
source_files	Maps files to sources	Stores source_id (int), returns formatted S IDs
citation_links	Links citations to facts	Stores entity_id (int) and entity_type (text)
event_participants	Maps people to events	Stores individual_id and event_id

Sources: src/db/trees/files.ts:145-157, src/db/trees/citations.ts:184-205, src/db/connection.ts:251-267

Entity ID Exceptions

Not all entities use prefixed IDs. For instance, names records are typically identified by a standard string representation of their database integer, as they are considered sub-entities of an Individual rather than top-level citable entities in some contexts.

Sources: src/db/trees/citations.ts:125-127

Conclusion

The Entity ID System provides a consistent, type-safe way to reference genealogical data. By decoupling the internal database keys from the application-level identifiers, Vata maintains high performance while offering a developer-friendly and user-readable ID structure that remains compatible with genealogical industry standards.

Sources: CLAUDE.md:74-86, src/db/trees/citations.ts:114-130