Overview
A deep introduction to the Canonical Timeline system — what it is, how it works, and why it was built.
1. What Canonical Timeline Is
Canonical Timeline is a chronology exploration system built for evidence professionals. It turns sequences of events, sourced claims, and entity networks into rigorous, auditable, and exportable investigations.
The system is structured around a five-layer model:
- Timelines — Scoped investigation containers with defined status (fact-finding, verification, ongoing, resolved) and multi-tenant access control.
- Events — Time-anchored nodes with fuzzy/ISO 8601 timestamps, time precision grading (exact through estimated range), and 9 status values from
reportedthroughretracted. - Claims — Factual assertions linked to events and sources, each carrying a confidence score (0–100) and a claim status (
rumored,reported,unverifiable,verifiable,fact). - Sources — Reference documents (175+ source types: news articles, intelligence reports, satellite imagery, diplomatic cables, flight logs, leaked documents) with checksum-verified file attachments.
- Entities & Relationships — Named actors (170+ entity types: people, organizations, military units, shell companies, vessels, front companies) connected by directed, time-scoped, confidence-weighted relationships.
2. What Canonical Timeline Is Not
Not a social media feed.
The system has no algorithmic engagement, no "trending" sorting, no follower counts, no public commenting, no virality mechanics. Events are ordered by canonical time, not by engagement. The system was built for a different incentive structure: accuracy over attention.
Not a project management timeline.
This is not a Gantt chart or Jira roadmap. There are no deadlines, no assignees, no sprint tracking, no burndown charts. The system models what happened, not what should happen. It is forensic, not predictive.
Not a generic event database.
Every event, claim, source, and relationship is scoped to an account — the data model is multi-tenant with role-based access control (owner, admin, contributor, reader). There is no global public feed. Investigations are siloed by design. The system does not aggregate "consensus truth" across accounts — it records each team's independent evidence assessment. The system is infrastructure for building truth, not a content platform.
3. The Curation Methodology
The curation methodology embedded in Canonical Timeline is a structured, repeatable process for transforming raw information into verifiable chronologies. Each step engages one or more layers of the data model, but the workflow describes actions a curator takes across layers — it is not a 1:1 mapping to the five-layer taxonomy.
- Scope — Define the timeline boundary. What question is being investigated? What period? The timeline is a contract: everything within it is in scope; everything outside is noise.
- Aggregate — Add events with the best available timestamps. The system accepts precision qualifiers (exact, estimated, range) because real investigations rarely have perfect dates.
- Source — For every factual assertion (claim), attach a verifiable source. Sources have types, publishers, publication dates, checksums, and raw file uploads. The system distinguishes between a news article, a government report, a leaked document, and a witness statement — and treats them differently.
- Verify— Grade each claim's accuracy using a structured scale: rumored → reported → unverifiable → verifiable → fact. The curator (or their chosen AI agent) assigns every confidence score — the system never asserts truth. It provides the framework; the human determines the facts based on the evidence they collect. Confidence scores are quantitative, auditable, and always traceable to a specific curator's judgment.
- Relate — Link entities to events, entities to entities, and events to events. Build the graph. The system supports relationship types from
knowsandworks_fortowitness_toandinvolved_in, each time-scoped withvalid_from/valid_toand weighted with confidence scores. - Audit — Every change is recorded in an append-only revision log with
previous_stateandnew_stateas JSONB diffs. Nothing is ever truly deleted — objects are soft-deleted and recoverable.
4. Investigation Tools
Beyond basic event curation, the system provides three analytical tools for cross-referencing and pattern detection:
Timeline Comparison
Up to three timelines side-by-side in independent scrollable columns with drag-to-reorder. Built for discrepancy detection: the same event reported differently across timelines surfaces immediately. The system already ships with paired demo timelines (CT-451 official vs. alternative narrative; Helsinki Handoff CIA vs. KGB perspective) that demonstrate this capability.
Entity Relationship Graph
An interactive graph visualization with nodes proportional to connection count, edges colored by relationship type with directional arrows, and cross-timeline mode with distinct visual warnings. Supports pan/zoom, click-to-detail panels, search-to-highlight, and saved node positions per account.
Timeline Map
Geographic visualization of event locations with grouped markers, bounding box calculations, and numbered event overlay.
5. Workspace and Triage
Curation is not a one-time import — it is an ongoing process of refinement. The workspace page provides an analyst cockpit with structured triage queues that surface gaps, low-quality data, and items needing attention:
- Events Without Claims — identify gaps in evidence
- Sources Pending Extraction — process raw documents
- Low-Confidence Claims — flag assertions needing verification
- Orphan Entities — find entities not linked to any event
- Claims Needing Status Review — ensure classification is current
- Events Flagged for Review — triage based on
needs_reviewflag
The workspace also surfaces timeline health stats: claim coverage percentage, confidence score distribution, and status breakdowns — giving curators a quantitative view of their investigation's completeness.
6. Real-World Application Domains
Investigative Journalism
Newsrooms tracking fast-moving stories need to archive primary sources before they disappear, track evolving narratives across multiple outlets, and defend their reporting with verifiable provenance.
The Watergate demo timeline traces 12 events from the June 1972 break-in through Nixon's resignation, linked via caused_by relationships forming a complete causal chain. It maps 10 entities (Nixon, Woodward, Bernstein, Haldeman, Ehrlichman, Dean, Sirica, Cox, Butterfield, The Washington Post) with relationship types like works_for, works_with, and involved_in. Claims cite 12 sources: news articles, court documents, government records, testimonies, and a presidential speech.
Intelligence and Competitive Analysis
Analysts building entity relationship maps to trace connections between corporate shells, bad actors, or state-linked organizations. The system supports shortest-path algorithms between any two entities, event-to-event pathfinding, and shared-event discovery between entities.
The Operation Ghost Courier investigation spans four related timelines, including two competing Helsinki Handoff narratives — one from CIA perspective (a successful double agent recruitment of NIGHTINGALE) and one from KGB perspective (contact rejected). The same event, two contradictory claims, graded with divergent confidence scores (CIA: 0.80–0.95, KGB: 0.40–0.65). Entity types include double_agent, operative, courier, front_company, bank, and government_agency. Sources include intelligence_report, wire_intercept, and diplomatic_cable.
Fact-Checking Organizations
Maintaining a structured repository of assertions with status grading, supporting source metadata, and export feeds for downstream consumers. Claims can be filtered by status, confidence, and supporting source to generate curated exports.
The same data model supports both "this claim is true" and "this claim is false" — the claim status scale runs from rumored through fact, and claims proven false can be linked to contradictory evidence via event relationships using the contradicted event status. Events carrying disproven claims are kept in the record (nothing is hard-deleted), with their status changed to reflect the contradiction.
AI and LLM-Aided Curation
Structured CSV and JSON exports (per-timeline canonical sequences) feed into language models, newsletter automation systems, or research pipelines. An MCP (Model Context Protocol) server is available for AI tools to query timelines, events, and entities — turning Canonical Timeline into structured context for LLM reasoning without hallucination. The SSE endpoint and client configuration are documented at /app/api-reference.
7. The Data Model as Philosophy
The architectural choices in Canonical Timeline are not arbitrary — they encode real-world domain wisdom about how evidence is gathered, graded, and defended.
The System Does Not Decide What Is True
Every confidence score, every claim status, every relationship weighting is assigned by a human curator (or an AI agent working at their direction). Canonical Timeline has no internal truth model, no automated fact-checking engine, and no algorithmic authority over what is "verified." It is a structured toolkit for organizing evidence — the judgments are yours.
This separation is fundamental: the system records who asserted what, with what confidence, citing what source, at what time. It never makes the assertion itself. This distinction preserves editorial accountability and ensures the system remains usable across adversarial contexts where two curators may grade the same event with opposite confidence scores (as demonstrated in the Helsinki Handoff CIA/KGB demo timelines).
Time Precision, Not Time Certainty
The system accepts exact, estimated_date_time, exact_time_period_range, and estimated_time_period_range. It also models time_confidence (0–100) on every event. This matters because most real-world events do not have precise to-the-second timestamps. A tool that demands exact times forces the curator to fabricate precision. This tool forces the curator to be honest about uncertainty.
Status Scales for Every Object
Events have 8 status values (reported through retracted). Claims have 5 (rumored through fact). Timelines have 4 (fact-finding through resolved). These are not trivia — they are the operational language of verification. A timeline in fact-findingstatus signals "we are still gathering, expect gaps." An event with allegedstatus signals "this may not be true." A claim with confidence 0.45 and status rumoredsignals "do not rely on this." Every status is a communication protocol between curators and consumers.
Revision as First-Class Infrastructure
Every mutation generates an append-only revision record with full before/after snapshots. There is no "oops I changed it" — there is a permanent, queryable record of who changed what and when. This is table stakes for any system that aspires to be used in legal, journalistic, or intelligence contexts.
Multi-Tenant with Bundled Demos
Accounts are isolated. Each account has its own timelines, events, entities, sources, and type taxonomies. But the system ships with curated demo datasets (Apollo 11, Watergate, Berlin Wall, CT-451, Operation Ghost Courier, Challenger) that can be activated per-account as read-only templates. This solves the cold-start problem: new accounts can immediately explore a fully populated investigation without building from zero.
Extensible Type System
The 175+ source types, 170+ entity types, 180+ relationship types, and 150+ event types are not hardcoded. Each is a database row with name, description, color, icon, and account scope. Accounts can create, hide, and manage their own taxonomies. This means the system can model a missile_launch event in a military investigation and a press_release in a media investigation — without schema changes.
8. Technical Positioning
Architecture
The system is a browser-based frontend with a compiled backend service backed by PostgreSQL. Authentication uses signed session cookies with API key delegation. Multi-tenancy is enforced at the database query level — every query is scoped to an account.
API-First
Every operation available in the UI is also available via REST API. The full OpenAPI specification is served at /app/api-reference. API keys are generated per-user per-account with the ability to revoke individually.
MCP Integration
An MCP (Model Context Protocol) server is available through the Developer API for LLM clients to query timelines, events, and entities. This means Canonical Timeline serves as structured context for AI tool use — a researcher can ask their LLM "what was the timeline of the Watergate investigation?" and receive structured, provenance-backed data rather than hallucinated synthesis. The MCP SSE endpoint and client configuration are documented on the /app/api-reference page.
Export Formats
Every timeline exports to CSV and JSON. These are not generic data dumps — they are structured canonical sequences ordered by time, with nested claims, sources, and entity references. They are designed to be consumed by downstream pipelines: newsletters, dashboards, research databases, or LLM context windows.
No Vendor Lock-In
All data is exportable. The OpenAPI spec is public. The source type taxonomies are queryable. An organization can leave with every byte of their curated data in machine-readable formats.
9. What This System Demands
Canonical Timeline is not a casual tool. It rewards rigorous methodology and punishes sloppy data entry. Before adopting it, consider what the system expects:
- Discipline — The system rewards structured thinking. Every event needs a timestamp (even an estimated one). Every claim should cite a source.
- Process commitment — The workspace queues are only useful if someone works them. The tool surfaces gaps; it cannot fill them.
- Technical comfort — The system assumes curators are comfortable with structured data. It does not have a WYSIWYG narrative editor. It is not a note-taking app.
What you invest in structure, you get back in precision. A well-curated timeline is not just a document — it is a verifiable, queryable, exportable asset that compounds in value as more events, claims, and relationships are added.