Sources & Repositories Management

Relevant source files

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

• src/db/trees/sources.ts
• src/db/trees/repositories.ts
• src/db/trees/citations.ts
• src/db/connection.ts
• src/managers/SourceWorkspaceManager.ts
• src/db/trees/files.ts
• CONTEXT.md

Sources and Repositories Management in Vata provides the infrastructure for documentary evidence within a family tree. This system allows researchers to record the origin of genealogical facts, ranging from physical archives (Repositories) to specific documents (Sources) and the precise references within them (Citations).

The system follows a hierarchical structure where a Repository (e.g., a national archive) holds many Sources (e.g., a specific census book), and each Source is referenced via one or more Citations (e.g., a specific page number). These citations act as the bridge to genealogical entities like Individuals, Families, or Events, providing proof for recorded data.

Sources: CONTEXT.md

Data Architecture & Relationships

The relationship between these entities is strictly defined to maintain data integrity and GEDCOM 5.5.1 compatibility. While a Source belongs to a Repository, genealogical entities never link to a Source directly; they are always linked via a Citation.

Entity Relationship Diagram

The following diagram illustrates the cardinality and linking logic between repositories, sources, citations, and evidence files.

Data Models

The system uses specialized TypeScript types that map to SQLite rows. Database interactions follow a pattern of mapping Raw snake_case database rows to camelCase domain objects.

Entity	Description	Key Fields
Repository	An institution holding sources.	name, address, city, phone, email, website
Source	A piece of documentary evidence.	title, author, publisher, publicationDate, callNumber, url
Citation	A specific reference into a Source.	page, quality, dateAccessed, text
Media File	Digital assets (scans/photos).	originalFilename, relativePath, mimeType, fileSize, thumbnailPath

Sources: src/db/trees/repositories.ts:9-40, src/db/trees/sources.ts:9-40, src/db/trees/files.ts:16-52, src/db/connection.ts:333-356

Repositories Management

Repositories represent the physical or digital locations where sources are stored. They are managed through the repositories.ts module, providing standard CRUD operations.

Database Schema (SQLite)

CREATE TABLE IF NOT EXISTS repositories (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL,
  address TEXT,
  city TEXT,
  country TEXT,
  phone TEXT,
  email TEXT,
  website TEXT,
  notes TEXT,
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at TEXT NOT NULL DEFAULT (datetime('now'))
);

Sources: src/db/connection.ts:285-300

Core Functions

• getAllRepositories(): Retrieves all repository records ordered alphabetically by name.
• createRepository(input): Inserts a new repository and returns a formatted ID (e.g., R-0001).
• searchRepositories(query): Performs a LIKE search on the repository name.

Sources: src/db/trees/repositories.ts:47-113

Sources Management

Sources are the specific records (books, certificates, digital databases) held within repositories.

Data Flow for Source Creation

When a source is created, it optionally links to a repository_id. The application enforces explicit column selection to avoid performance overhead.

Media Integration

Sources can have multiple digital files attached (e.g., high-resolution scans of a document). This is handled via the source_files junction table which supports custom sorting.

• addFileToSource(input): Links a TreeFile to a Source.
• getFilesBySourceId(sourceId): Retrieves all media attached to a source, ordered by sort_order.

Sources: src/db/trees/files.ts:101-136

Citations & Evidence Linking

Citations are the most granular level of the evidence system. They allow a single source to support multiple genealogical facts with different details (e.g., different pages in the same book).

Citation Reliability (Quality)

Vata implements a quality field for citations to assess the reliability of evidence, constrained by the following values:

• primary
• secondary
• questionable
• unreliable

Sources: src/db/connection.ts:337

Entity Linking Logic

Citations are linked to entities through the citation_links table. This allows a citation to be attached to an Individual, Name, Event, Family, or Place.

// Example of creating a link between a citation and an individual
export async function createCitationLink(input: CreateCitationLinkInput): Promise<string> {
  const db = await getTreeDb();
  const dbCitationId = parseEntityId(input.citationId);
  const dbEntityId = parseEntityId(input.entityId);
  
  const result = await db.execute(
    `INSERT INTO citation_links (citation_id, entity_type, entity_id, field_name)
     VALUES ($1, $2, $3, $4)`,
    [dbCitationId, input.entityType, dbEntityId, input.fieldName ?? null]
  );
  // ... returns link ID
}

Sources: src/db/trees/citations.ts (inferred from usage in Manager), src/db/connection.ts:355-365

Source Workspace Orchestration

The SourceWorkspaceManager provides high-level workflows to automate the creation of complex evidence structures. It allows users to create individuals, families, and events simultaneously from a single source template (e.g., a "Marriage Record" template).

Automated Workflow Sequence

1. Resolve Individuals: Identifies if persons in the source are new or existing in the tree.
2. Create Entities: Generates Events and Families based on template definitions.
3. Generate Citation: Creates a single Citation for the source.
4. Link Everything: Automatically creates citation_links for every individual, family, and event involved in the transaction.

Conclusion

The Sources & Repositories system in Vata ensures that every genealogical claim is backed by verifiable evidence. By separating the physical storage (Repositories), the document (Sources), and the specific reference (Citations), Vata provides a flexible and precise research environment that scales from simple family trees to complex professional projects.