Core Concepts

← Back to Documentation Index

Understanding Canonical Timeline starts with its six-layer data model. Every piece of evidence in your investigation lives in one of these layers.

The Six-Layer Data Model

1. Investigations

An investigation is the top-level workspace — a project container that holds a primary timeline along with evidence, entities, relationships, notes, and questions.

Every investigation has:

• Title — a descriptive name (e.g., "Acme Corp Insider Trading Investigation")
• Status — draft, active, paused, resolved, or archived
• Summary — a description of scope, goals, and context
• Health — aggregate metrics: claim coverage, event source coverage, entity connectedness, review completion

Investigations are navigated through seven lenses (tabbed views):

An investigation is a contract: everything within it is in scope for your project. Everything outside is noise.

2. Timelines

A timeline is the chronological container for events within an investigation. Each investigation has one primary timeline. It defines:

• Title — a descriptive name
• Slug — a URL-safe identifier
• Status — the investigation phase: draft, active, paused, resolved, or archived

Each timeline contains events, which contain claims, which cite sources. Entities can be linked across investigations.

3. Events

An event is a time-anchored node — something that happened at a specific point in time.

Every event has:

• A title — a concise description (e.g., "Board meeting at HQ")
• A canonical time — the best-known timestamp (ISO 8601)
• A time precision — how certain you are about that time
• A status — the verification state
• An optional description — context and details
• An optional location — geographic coordinates or named place

Events appear in chronological order within their timeline.

Time Precision Levels:

The system also tracks a time_confidence score (0–100) on every event. If you don't know the exact time, be honest about your uncertainty. The tool demands honesty, not fabricated precision.

Event Statuses:

4. Claims

A claim is a factual assertion attached to an event, backed by a source.

Claims are the connective tissue between what happened (the event) and the evidence (the source). Every claim has:

• Claim text — the assertion itself (e.g., "The CEO was present at the board meeting")
• Source — the document or reference that supports (or refutes) this claim
• Claim status — the verification grade
• Confidence score — your quantitative confidence (0–100)

Claim Statuses:

Claims proven false are not deleted. Their status is changed to reflect the contradiction. The revision history preserves every judgment for audit.

Confidence Score:

The confidence score is a number from 0 to 100 (displayed as a percentage). It represents your assessment of the claim's accuracy:

• 0–25: Very low confidence — the claim is highly uncertain
• 26–50: Low confidence — more evidence needed
• 51–75: Moderate confidence — supported by evidence but not definitive
• 76–100: High confidence — well-sourced and verified

Confidence is always the curator's judgment. The system never asserts truth — it records who asserted what, with what confidence, citing what source. This preserves editorial accountability and makes the system usable in adversarial contexts where two curators may grade the same claim differently.

5. Sources

A source is a reference document that supports one or more claims. Sources are the foundation of every investigation's credibility.

Every source has:

• Title — the document's name
• Source type — one of 175+ types (e.g., news_article, court_document, intelligence_report, satellite_imagery, diplomatic_cable, leaked_document)
• Author — who created or published it
• Publication date — when it was published
• URL — a link to the source (if online)
• Checksum — a hash of the uploaded file for integrity verification
• File attachments — uploaded documents (PDFs, images, text files)
• Extracted content — text extracted from uploaded files or crawled URLs

Sources can be linked to claims. A single source can support multiple claims across different events.

6. Entities and Relationships

An entity is a named actor — a person, organization, object, or concept relevant to your investigation.

Every entity has:

• Canonical name — the full, official name (e.g., "John D. Rockefeller")
• Aliases — alternative names or code names
• Entity type — one of 170+ types (e.g., person, corporation, government_agency, military_unit, shell_company)

Entities can be:

• Linked to events — an entity participated in or was affected by an event
• Related to other entities — directed relationships like works_for, owns, reports_to

Relationship properties:

• Direction: from one entity to another (e.g., Alice → works_for → Acme Corp)
• Time scoping: valid_from and valid_to dates — a relationship might only have existed during a specific period
• Confidence: how sure you are about this relationship

The Entity Reconciliation tool (sidebar > Management) scans for potential duplicate entities and provides a merge interface.

The Curation Methodology

Canonical Timeline encodes a structured process for building and verifying chronologies:

1. Scope — Define the investigation boundary. What question are you investigating? What period?
2. Aggregate — Add events with the best available timestamps, using the precision qualifier that matches your certainty.
3. Source — For every factual assertion, attach a verifiable source. The system distinguishes between types of sources and treats them differently.
4. Verify — Grade each claim's accuracy using the status scale and confidence score.
5. Relate — Link entities to events, entities to entities, and events to events. Build the graph.
6. Audit — Every change is recorded in an append-only revision log. Nothing is ever truly deleted.

Key Design Principles

The System Does Not Decide What Is True

Every confidence score, every claim status, every relationship weighting is assigned by a human curator. The system records who asserted what, with what confidence, citing what source, at what time. It never makes the assertion itself.

Time Precision, Not Time Certainty

Real-world events rarely have precise timestamps. The system accepts uncertainty ranges and confidence qualifiers. A tool that demands exact times forces the curator to fabricate precision. This tool forces you to be honest about what you don't know.

Investigation-First Organization

Data is organized around investigations — project containers that group timelines, claims, sources, entities, and relationships together. Navigation stays within the investigation context, so clicking an event from the Evidence lens keeps you within the same investigation.

Status Scales for Every Object

Statuses are the operational language of verification. An investigation in draft signals "expect gaps." An event with alleged status signals "this may not be true." A claim with confidence 45 and status rumored signals "do not rely on this."

Revision as First-Class Infrastructure

Every mutation generates an append-only revision record with before/after snapshots. There is a permanent, queryable record of who changed what and when.

Multi-Tenant with Bundled Demos

Accounts are isolated. Each has its own investigations, timelines, events, entities, and sources. Demo datasets (Apollo 11, Watergate, Operation Ghost Courier) can be activated per-account as read-only templates.

Extensible Type System

The 175+ source types, 170+ entity types, and relationship types are database rows — not hardcoded. Accounts can create, hide, and manage their own taxonomies via Type Management.

Next: Working with Investigations →