Events & Places Tracking

Relevant source files

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

• src/db/connection.ts
• src/db/trees/events.ts
• src/db/trees/event-timeline.test.ts
• src/pages/EventsPage.tsx
• src/types/database.ts
• src/managers/EventManager.test.ts

The Events & Places Tracking system is a core component of the Vata application, responsible for managing the historical lifecycle of individuals and families. It facilitates the recording of standardized and custom event types (such as births, marriages, and deaths) and associates them with specific geographic locations (places). The system is designed to handle complex relationships, including multi-participant events and hierarchical place structures.

This module ensures data integrity through a structured SQLite schema within the Tree Database, supporting GEDCOM-compliant date handling and rich metadata association, including citations and media thumbnails for event timelines.
Sources: src/db/connection.ts:88-185, src/types/database.ts:223-305, README.md:13-17

Data Architecture

The system utilizes a relational structure to link events, participants, and locations. Events are categorized into individual or family scopes, and locations are managed through a hierarchical places table.

Database Schema Relationships

The following diagram illustrates the entity relationships between events, their types, participants, and geographic locations.

The relationship between Events and Places is optional, while an Event must always have a defined Event Type.
Sources: src/db/connection.ts:88-185, src/types/database.ts:223-305

Core Data Models

Entity	Description	Key Fields
Event	A specific historical occurrence.	id, eventTypeId, dateOriginal, placeId, description
EventType	Definition of an event category.	id, tag (GEDCOM), category, isSystem, customName
EventParticipant	Links an individual or family to an event.	eventId, individualId, familyId, role
Place	A geographic location.	id, name, fullName, parentId, latitude, longitude

Sources: src/types/database.ts:182-305, src/db/connection.ts:154-185

Event Management

Events are managed through specialized CRUD operations and bulk fetch helpers that optimize data retrieval for list views and timelines.

Event Lifecycle and Resolution

When fetching events, the system resolves "Principals" to identify the primary subjects of an event. For individual events (e.g., Birth), this is typically the person; for family events (e.g., Marriage), it involves multiple spouse slots.

This flow ensures that UI components receive enriched data ready for display without additional queries.
Sources: src/db/trees/events.ts:185-210, src/db/trees/events.ts:503-535, src/managers/EventManager.test.ts:36-77

Standardized Event Types

The system prepopulates several standard GEDCOM event types during database initialization.

Tag	Category	Description
BIRT	Individual	Birth
DEAT	Individual	Death
MARR	Family	Marriage
DIV	Family	Divorce
CENS	Individual	Census
BURI	Individual	Burial

Sources: src/db/connection.ts:114-152

Geographic Tracking (Places)

Places are stored with a hierarchical structure, allowing for "drill-down" geography (e.g., a City belonging to a County, belonging to a State).

Place Structure Implementation

Places include both a short name and a full_name (often a comma-separated string of the hierarchy). The parent_id field enables the tree structure.

// From src/db/connection.ts
await db.execute(`
  CREATE TABLE IF NOT EXISTS places (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    full_name TEXT NOT NULL,
    place_type_id INTEGER,
    parent_id INTEGER,
    latitude REAL,
    longitude REAL,
    FOREIGN KEY (parent_id) REFERENCES places(id) ON DELETE SET NULL
  )
`);

Sources: src/db/connection.ts:88-106

UI Integration

The EventsPage component renders a comprehensive table of every event in the open tree, utilizing TanStack Table logic for sorting and navigation.

Event List Resolution Logic

The UI resolves complex principal relationships for display, joining names with "&" for family events or falling back to "Unknown" labels.

Event Timelines and Citations

For individual profiles, the system generates a chronological timeline that aggregates events, their associated citations, and media thumbnails.

• Citations: Events can be linked to sources via citation_links to provide historical evidence.
• Media: If a source citation has associated files (e.g., a scan of a birth certificate), the timeline retrieves thumbnailPath for visual representation.
• Deduplication: Bulk fetch helpers ensure that even if an event has multiple participants, it is retrieved once during batch loading.

Sources: src/db/trees/event-timeline.test.ts:83-145, src/db/trees/events.ts:503-535, src/types/database.ts:468-477

Conclusion

The Events & Places Tracking system provides the foundational structure for genealogical data in Vata. By combining a flexible participant-role model with hierarchical geographic tracking, it supports detailed historical narratives while maintaining high performance through optimized bulk-query operations.