Crate Map

relata-core is the dependency root — every other crate in the workspace depends on it. The next ring is storage + query + canonical + ontology. The outer ring is server, CLI, and domain modules. Dependency arrows always point inward toward relata-core; no inner crate depends on an outer crate.

Dependency graph

                      ┌──────────────┐
                      │ relata-core  │  ← every crate depends on this
                      └──────┬───────┘
           ┌─────────────────┼─────────────────┐
           ▼                 ▼                 ▼
    relata-canonical   relata-storage    relata-ontology
           │                 │                 │
           └────────┬────────┘                 │
                    ▼                          │
             relata-query ◄────────────────────┘
                    │
      ┌─────────────┼──────────────┐
      ▼             ▼              ▼
relata-graph   relata-acl    relata-identity
      │             │              │
      └─────┬───────┴──────┬───────┘
            ▼              ▼
      relata-prov    relata-detect
            │              │
            └──────┬───────┘
                   ▼
            relata-server ◄── relata-cluster, relata-cache
                   │
                   ▼
             relata-cli

Foundation

CrateLayerRole
relata-coreFoundationCore types: bi-temporal row model, ObjectId / LinkId / EventId / RowId (16-byte newtypes; production RowId is a server-minted counter — see Data Model), Identity datatype, HLC timestamps. The one crate that depends on nothing else in the workspace.

Storage and data plane

CrateLayerRole
relata-storageStorageIn-memory bi-temporal store with per-type interior locking (&self writes via PlRwLock). WAL. Custom BM25 full-text (integer posting lists + q-gram prefix + trigram suffix + 15 hand-rolled stemmers (en/fr/de/es/pt/it/nl/sv/no/da/fi/hu/ro + Russian Cyrillic, Turkish, Arabic) + CJK pass-through + subword tokenization (camelCase/digit); NOT Tantivy). Vectors: custom HNSW (vector.rs) + DiskANN warm tier (vector_diskann.rs). Backup/restore. Per-column bloom filters. Summary index for O(1) COUNT/SUM. HLL + CMS cardinality sketches. Pure-Rust Kafka ingest adapter. Arena allocation via bumpalo.
relata-canonicalStorage~76 canonical type validators shipped (email, IBAN, MMSI, VIN, IMEI, MSISDN, Aadhaar, GeoPoint, and more). Deterministic binary encoding. The target catalogue is ~170; the shipped count is in crates/relata-canonical/src/lib.rs.
relata-ontologyStorageSchema-as-code. Git-branched ontology with HEAD pointer. State-machine constraints on PropertySpec. Computed columns.

Query and compute

CrateLayerRole
relata-queryQuerySQL parser → planner → executor. DataFusion bridge for columnar aggregation. Cost-based optimizer (join ordering + index selection). MV refresh (ON COMMIT, IncrementalAggregate + HLL). Watch subscriptions. Query result cache. Pattern tracker + speculative prefetch. ReadOptions / WITH CACHE.
relata-graphQueryCSR adjacency. BFS/DFS. Pregel-style iterative BFS. PLL distance index (pll.rs) wired into GRAPH_SSSP (algo => 'pll') and GRAPH_DIJKSTRA (reachability pre-check); PATHS_BETWEEN uses BFS/DFS. 10+ SQL graph operators (GRAPH_DIJKSTRA, GRAPH_LINK_PREDICT, GRAPH_SCC, GRAPH_CYCLES, GRAPH_SSSP, GRAPH_SPANNING_TREE, GRAPH_APSP, GRAPH_DIAMETER, GRAPH_SIMILARITY, GRAPH_NODE_METRIC). Incremental degree index, exposed as the DEGREE() SQL function.

Identity and detection

CrateLayerRole
relata-identityDomainIdentityIndex materialized view. RESOLVE_IDENTITY, IDENTITY_CLUSTER, and SAME_IDENTITY SQL operators. Substrate for cross-source fusion.
relata-detectDomainTwo-phase SmartIngest: eager (validate + canonicalize in the writer's commit path) and lazy (DETECT_IDENTITIES operator run by the indexer). Configurable detector packs: network, contact, crypto (default on); financial, payment, social, transport, device, ics (opt-in); all, none.

Governance and trust

CrateLayerRole
relata-aclTrustCedar-inspired ABAC. Deny-wins evaluation. Bitmap row filtering (precomputed per (principal, type)). Cell masking (redact / hash / partial).
relata-provTrustPROV-O assertions. Hash-chained commit manifests. Content-addressed blobs. Audit log replay.

Server and clients

CrateLayerRole
relata-serverServerPostgres wire protocol + gRPC + Arrow Flight + MCP. Auth: OIDC, mTLS. Hosts the query coordinator on server/cluster profiles.
relata-cliServerThe relata binary entry point. Profiles: free / server / cluster (lite is a removed legacy alias — rejected at startup). Hosts the protocol-compatibility servers: s3_server.rs, pgwire_listener.rs, clickhouse_server.rs, neo4j_server.rs, redis_server.rs, mongo_server.rs, bolt_server.rs.
relata-sdk-rustClientInternal/reference client (not a published consumer SDK — Python/TypeScript/Go are the published SDKs). gRPC + HTTP + in-memory client. Arrow-IPC zero-copy. RFC 7807 error shape. Multi-tenant headers. SearchBuilder for the /search API. Used by the server binary, the tray app, the test harness, and relata-bench.

Cluster and cache

CrateLayerRole
relata-clusterDistributionCoordinator / reader / writer / indexer roles. Hash partitioning. Multi-region replication. Branch-level writer leases. Status: alpha — not recommended for production.
relata-cacheCacheRAM-only foyer cache. S3-FIFO admission (scan-resistant).

Intelligence and feeds

CrateLayerRole
relata-feed, relata-feed-brokerIntelligenceRIFN intelligence feed network. Inbound feed ingestion and fan-out.
relata-jobsIntelligenceContinuous pattern-detection jobs (C2 beacon, convoy, transaction ring). Governance-aware DAG workflow engine.
relata-intelligenceIntelligenceIncident clustering. Anomaly detection. LLM interpretation. Detection-rule tuning: snooze, suppression, exception lists.

Extension points

These crates define the contract that external extension crates must implement. They are not run directly.

CrateRole
relata-connector-stubTrait shapes for external relata-connector-* crates (data source connectors).
relata-pack-stubTrait shapes for external relata-pack-* crates (domain-specific intelligence packs).

Domain packs and connectors live in separate repositories (relata-pack-*, relata-connector-*). They are not part of this workspace.

Benchmarks

CrateRole
relata-bench50+ benchmarks + conformance runner. --gate quick pre-merge (~30s). --no-ann skips HNSW builds (~8 min vs. ~15 min). Protocol coverage for all 8 compat doors + 5 native protocols. Not in the workspace test gate; run separately.

Testing

CrateRole
relata-testingIn-process test fixtures. TestFixture spins up an in-memory ObjectStore; spawn_ephemeral (behind the ephemeral feature) starts a real relata process on a random port for SDK integration tests. Consumed by the workspace test gate, not shipped at runtime.

Apps

Console and Portal live in SEPARATE repositories (github.com/relatadb/console and github.com/relatadb/portal), not in this workspace. Only apps/relata-tray ships in-repo. They are listed here for orientation; they are not part of the Rust workspace test gate.

AppRepoRole
Consolegithub.com/relatadb/console (separate repo)Next.js showcase + ops surface. 68 pages, 19 tutorials, 24 docs, 8 interactive showcases. Force-directed graph explorer, universal search, CDR/SDR analyzer, case investigator. Talks to the server via /api/relata/* proxy.
Portalgithub.com/relatadb/portal (separate repo — this site)Next.js docs and landing site. Hand-authored rolling-latest surface with per-version snapshots.
apps/relata-trayin-repomacOS menu-bar app (Tauri 2). Click-to-launch server + popup health WebView. Bundled in the DMG release.

Build invariants

These are enforced at the workspace level, not per-crate.

No unsafe in library code. Every lib.rs compiles with unsafe_code forbidden or denied — most carry #![forbid(unsafe_code)]; relata-query and relata-storage carry #![deny(unsafe_code)]; relata-cluster forbids it outside tests. The single workspace exception is the relata CLI binary, whose smoke-test harness uses a minimal libc::kill FFI shim.

missing_docs is denied. Every public item has a doc comment. Builds fail otherwise.

Workspace resolver "3", edition 2024, MSRV 1.85.

parking_lot locks only. PlMutex and PlRwLock type aliases are the only mutexes used. parking_lot does not poison on panic.

Workspace dependency pinning. All shared dependency versions live in [workspace.dependencies]. Use dep.workspace = true, not inline version strings.

cargo deny check enforces a license allowlist and bans unknown registries and git dependencies.

See also