Skip to main content

Knowledge Graph

The knowledge graph is the architectural centerpiece of GospeLib. FalkorDB is not a cache or secondary store -- it IS the product. Every passage, topic, lexicon entry, manuscript witness, cross-reference, and scholarly annotation lives in the graph as nodes and edges that users can traverse, visualize, and explore.

Overview​

The scripture knowledge graph contains 7 node types and 8 edge types, organized across 7 schema families. Each JSON file in the corpus declares its type via a schema field, and the 14-stage ingest pipeline transforms that corpus data into a fully connected graph.

Node TypeExamplesCount (approx.)
PassageEvery verse in every canonical text~41,000
LexiconEntryStrong's Hebrew and Greek dictionary entries~13,000
IndexTopicTopical Guide topics~600
BDArticleBible Dictionary articles~1,200
WordAlignmentInterlinear word-level mappings~300,000
WitnessManuscript witnesses, source editionsVaries
VerseNoteFootnotes and scholarly annotations~30,000

How Passages Connect​

Passage ---[CROSS_REF]---> Passage
   |                          |
   |--[HAS_WORD]--> WordAlignment --[DEFINED_BY]--> LexiconEntry
   |
   |--[HAS_NOTE]--> VerseNote
   |
   |--[HAS_ORIGINAL]--> Witness

IndexTopic --[CITES]--> Passage
   |
   |--[SEE_ALSO_TG]--> IndexTopic
   |--[SEE_ALSO_BD]--> BDArticle

A user reading Genesis 1:1 can tap a word to see its Hebrew root (WordAlignment to LexiconEntry), follow a cross-reference to John 1:1 (CROSS_REF edge), explore the "Creation" topic (IndexTopic that CITES this passage), or view manuscript variants (Witness nodes).

Study Map​

The Study Map is the visual interface to the knowledge graph. It renders a Sigma.js/Graphology WebGL canvas with force-directed layout (ForceAtlas2 in a Web Worker) where users can:

  • Explore connections -- Click a passage node to see its cross-references, topical links, and lexicon connections radiate outward
  • Build a study session -- Pin passages, topics, and dictionary entries to accumulate a personal constellation of connected ideas
  • Three zoom levels -- Constellation (high-level structure), Working (moderate detail), Reading (full node content)
  • Loose/pinned duality -- Nodes float with the force layout until explicitly pinned to a position

The Study Map persists sessions to Dexie.js (IndexedDB) so users can return to their study constellation across browser sessions.

Graph Queries​

The content service exposes the graph through several API patterns:

Passage Retrieval with Context​

MATCH (p:Passage {id: $passage_id})
OPTIONAL MATCH (p)-[:HAS_ORIGINAL]->(witness:Witness)
OPTIONAL MATCH (p)-[:CROSS_REF]->(ref:Passage)
WITH p, collect(DISTINCT witness) AS witnesses, collect(DISTINCT ref) AS refs
RETURN p, witnesses, refs

Connection Discovery​

MATCH (p:Passage {id: $passage_id})
MATCH (p)-[rel]->(connected)
RETURN type(rel) AS relationship_type,
       labels(connected)[0] AS node_type,
       connected.id AS connected_id
ORDER BY rel.weight DESC
LIMIT $limit

Topic Subgraph​

MATCH (t:IndexTopic {id: $topic_id})
MATCH (t)-[:CITES]->(p:Passage)
RETURN p

Deep Dive: Why FalkorDB?​

FalkorDB was chosen over Neo4j and ArangoDB for specific reasons:

  • Redis-based -- Operational simplicity; same protocol and tooling as Redis
  • Cypher-compatible -- Standard graph query language, no vendor lock-in on query syntax
  • In-memory performance -- Sub-millisecond for 2-3 hop queries, which is the typical depth for scripture connection discovery
  • Cost -- Open source, no per-node licensing fees that would grow with corpus size

The graph uses MERGE (never CREATE) for all writes, ensuring the ingest pipeline is fully idempotent and can be re-run without creating duplicate nodes.