Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Design

Architecture and design documents for Fluree’s internal systems. These documents describe the rationale behind key design decisions, wire formats, and trait architectures.

Documents

Query execution and overlay merge

How queries run through a single preparation/execution pipeline, how scan operators select the binary-cursor path vs the range fallback, and where overlay novelty merges with indexed data (including graph scoping boundaries).

Auth Contract (CLI ↔ Server)

Wire-level contract between the Fluree CLI and any Fluree-compatible server, covering OIDC device auth, token refresh, and storage proxy authentication.

Nameservice Schema v2

Design of the nameservice schema: ledger records, graph source records, configuration payloads, and the ref/config/tracking store abstractions.

Storage-agnostic Commits and Sync

How ContentId (CIDv1) values decouple the commit chain from storage backends, enabling replication across filesystem, S3, and IPFS. Includes the pack protocol wire format for efficient bulk transfer.

ContentId and ContentStore

The content-addressed identity layer: ContentId type, ContentStore trait, multicodec content kinds, and the bridge between CID-based identity and storage-backend addressing.

Index Format

Binary columnar index format: branch/leaf/leaflet hierarchy, dictionary artifacts, SPOT/PSOT/POST/OPST/TSPO layout, and encoding details.

Edge annotations (storage internals)

On-disk representation of RDF 1.2 edge annotations: the durable f:reifies* flake bundle, the derived EdgeKey ↔ subject annotation arena, the indexer state machine, and garbage-collection reachability. (User-facing contract lives in Edge annotations (concept doc).)

Spatial Index

Geospatial indexing internals: inline GeoPoint encoding (packed 60-bit lat/lng for POINT geometries with latitude-band scans) and the S2 cell-based index for complex geometries, plus the query pipeline and time-travel semantics.

Namespace allocation and fallback modes

How Fluree assigns ns_code values for IRIs (prefix trie matching, fallback split modes), including bulk-import preflight mitigation and how the “host-only” fallback persists for future transactions.

Ontology imports (f:schemaSource + owl:imports)

How the reasoner consumes schema from a named f:schemaSource graph and transitively resolves owl:imports: resolution order, the SchemaBundleOverlay projection, schema-triple whitelist, and caching.

Cross-ledger model enforcement

How a single model ledger can hold the ontology, SHACL shapes, policy rules, datalog rules, and uniqueness constraints that govern many data ledgers that reference it via f:GraphRef (f:ledger, f:atT). Specifies the shared resolver contract, term-space translation, policy IR identity split, failure variants, caching, and phasing.

Storage Traits

Storage trait architecture: StorageRead, StorageWrite, ContentAddressedWrite, Storage, and NameService trait design with guidance for implementing new backends.

Raft command queue and replicated state machine

How fluree-db-consensus replicates writes across a cluster: the queue → stage → apply flow, log entry types, snapshot model, and the rationale behind splitting “decisions” (in the Raft log) from “bytes” (in the shared content-addressed store). Operator-facing recipe lives in Raft clusters (replicated writes).