ADR 0002: DuckDB relational core, no graph database

Published

September 25, 2026

Context

IDEAS.md sketches course → event → objective → slide → concept relationships. The graph looks like a graph database, but every relationship we have today is a fixed-depth join over a few tables (about 4k events, 11k objectives, 138k pages).

Decision

One DuckDB file (data/atlas.duckdb), rebuilt from scratch by scripts/build_db.py from CSV/JSONL/Parquet pipeline outputs. Relationships are foreign-key columns (objectives.event_key, files.event_key, pages.rel_path). Full-text search uses DuckDB’s fts extension. External vocabularies (MeSH, frameworks, crosswalks) are ordinary tables.

Consequences

  • The whole database is disposable and reproducible, so there are no migrations.
  • Recursive questions (MeSH hierarchy, concept trajectories) use tree-number prefixes or recursive CTEs.
  • We revisit this only if a real use case needs traversals that SQL makes painful.