FlureeLabs

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.

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.

Storage Traits

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

Related Documentation