Concepts

Architecture, design rationale, and contributor deep-dives. Audience: contributors, curious users wondering “why is it built this way,” embedders trying to predict behavior.

For day-to-day usage see the Python guide or Rust guide.

Architecture + design

• Architecture — layered diagram, the petgraph storage, indexes, the query pipeline.

• Design decisions — the label model, why Cypher over SQL, transaction model.

• Multi-label rationale — why kglite chose single-label (vs Neo4j’s multi-label).

• Cypher conformance — what subset of Cypher kglite supports + three-valued logic + the conformance harness.

• Concurrency — the single-owner contract, freeze() snapshots for lock-free concurrent reads, Arc<DirGraph> mutation semantics, and GIL handling.

• Generated project facts — workspace, package, CI, storage, format, and benchmark facts derived from source.

Extending

• Adding a storage backend — trait surface + the in-memory / mapped / disk patterns.

• Adding a query language — Cypher and the fluent API are peers under languages/; the same shape works for SPARQL or a custom DSL.