# modernrelay/omnigraph architecture

> Architecture diagram of the GitHub repository modernrelay/omnigraph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/modernrelay/omnigraph
- Repository: https://github.com/modernrelay/omnigraph

## Overview

Omnigraph is an object-storage-native graph database for typed, versioned data and unified retrieval. A user works through the CLI or server; cluster configuration declares graphs, schemas, stored queries, and policies, then deployment applies them before queries and mutations run. The README also highlights branch-and-merge workflows, multimodal retrieval, security, and blob data. Several internal links below reflect documented capabilities; unsampled implementation details are not treated as verified call paths.

Main entry points: [`crates/omnigraph-server/src/handlers.rs`](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-server/src/handlers.rs) (Graph server), [`crates/omnigraph/src/engine/run.rs`](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph/src/engine/run.rs) (Query engine), [`crates/omnigraph/src/db/omnigraph.rs`](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph/src/db/omnigraph.rs) (Graph operations), [`crates/omnigraph-cluster/src/deployment.rs`](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-cluster/src/deployment.rs) (Cluster deploy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_graph_client["Graph client<br/>[client.rs]"]
  node_server["Graph server<br/>[handlers.rs]"]
  node_api_types["API contracts<br/>[lib.rs]"]
end

subgraph group_cluster["Cluster governance"]
  node_cluster_deploy["Cluster deploy<br/>[deployment.rs]"]
  node_schema_compiler["Schema compiler<br/>[parser.rs]"]
end

subgraph group_query["Query runtime"]
  node_query_compiler["Query compiler<br/>[parser.rs]"]
  node_planner["Query planner<br/>[optimizer.rs]"]
  node_query_engine["Query engine<br/>[run.rs]"]
  node_query_doors["Query entry points<br/>[query_doors.rs]"]
end

subgraph group_state["Graph state and storage"]
  node_graph_db["Graph operations<br/>[omnigraph.rs]"]
  node_branch_catalog[("Branch catalog<br/>[commit_graph.rs]")]
  node_table_storage["Staged table storage<br/>[storage_layer.rs]"]
  node_object_storage[("Lance storage backend<br/>[lib.rs]")]
end

subgraph group_security["Security and data"]
  node_policy["Cedar policies<br/>[lib.rs]"]
  node_blob_transport["Blob transport<br/>[blob_transport.rs]"]
end

node_agent(("Agent or UI"))

node_agent -->|"issues commands"| node_cli
node_agent -->|"sends requests"| node_server
node_cli -->|"dispatches commands"| node_graph_client
node_graph_client -->|"uses HTTP"| node_server
node_graph_client -->|"uses embedded engine"| node_graph_db
node_cluster_deploy -->|"applies schemas"| node_schema_compiler
node_cluster_deploy -->|"publishes policies"| node_policy
node_cluster_deploy -->|"creates graphs"| node_graph_db
node_server -->|"serves graph operations"| node_graph_db
node_server -->|"enforces policies"| node_policy
node_server -.->|"transfers blobs"| node_blob_transport
node_query_doors -->|"enters runtime"| node_query_engine
node_query_engine -.->|"uses compiled queries"| node_query_compiler
node_query_compiler -.->|"supplies query plans"| node_planner
node_planner -.->|"plans execution"| node_query_engine
node_query_engine -.->|"reads and writes"| node_table_storage
node_graph_db -.->|"tracks branch history"| node_branch_catalog
node_table_storage -->|"persists tables"| node_object_storage
node_cli -.->|"uses API contracts"| node_api_types

click node_cli "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-cli/src/main.rs"
click node_graph_client "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-cli/src/client.rs"
click node_server "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-server/src/handlers.rs"
click node_cluster_deploy "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-cluster/src/deployment.rs"
click node_schema_compiler "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-compiler/src/schema/parser.rs"
click node_query_compiler "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-compiler/src/query/parser.rs"
click node_planner "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-planner/src/optimizer.rs"
click node_query_engine "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph/src/engine/run.rs"
click node_query_doors "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph/src/exec/query_doors.rs"
click node_graph_db "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph/src/db/omnigraph.rs"
click node_branch_catalog "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-catalog/src/commit_graph.rs"
click node_table_storage "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph/src/storage_layer.rs"
click node_object_storage "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-storage/src/lib.rs"
click node_policy "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-policy/src/lib.rs"
click node_blob_transport "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-server/src/blob_transport.rs"
click node_api_types "https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-api-types/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_graph_client,node_server,node_api_types,node_agent toneBlue
class node_cluster_deploy,node_schema_compiler toneAmber
class node_query_compiler,node_planner,node_query_engine,node_query_doors toneMint
class node_graph_db,node_branch_catalog,node_table_storage,node_object_storage toneRose
class node_policy,node_blob_transport toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-cli/src/main.rs): `crates/omnigraph-cli/src/main.rs`
- [Graph client](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-cli/src/client.rs): `crates/omnigraph-cli/src/client.rs`
- [Graph server](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-server/src/handlers.rs): `crates/omnigraph-server/src/handlers.rs`
- [API contracts](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-api-types/src/lib.rs): `crates/omnigraph-api-types/src/lib.rs`

### Cluster governance

- [Cluster deploy](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-cluster/src/deployment.rs): `crates/omnigraph-cluster/src/deployment.rs`
- [Schema compiler](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-compiler/src/schema/parser.rs): `crates/omnigraph-compiler/src/schema/parser.rs`

### Query runtime

- [Query compiler](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-compiler/src/query/parser.rs): `crates/omnigraph-compiler/src/query/parser.rs`
- [Query planner](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-planner/src/optimizer.rs): `crates/omnigraph-planner/src/optimizer.rs`
- [Query engine](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph/src/engine/run.rs): `crates/omnigraph/src/engine/run.rs`
- [Query entry points](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph/src/exec/query_doors.rs): `crates/omnigraph/src/exec/query_doors.rs`

### Graph state and storage

- [Graph operations](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph/src/db/omnigraph.rs): `crates/omnigraph/src/db/omnigraph.rs`
- [Branch catalog](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-catalog/src/commit_graph.rs): `crates/omnigraph-catalog/src/commit_graph.rs`
- [Staged table storage](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph/src/storage_layer.rs): `crates/omnigraph/src/storage_layer.rs`
- [Lance storage backend](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-storage/src/lib.rs): `crates/omnigraph-storage/src/lib.rs`

### Security and data

- [Cedar policies](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-policy/src/lib.rs): `crates/omnigraph-policy/src/lib.rs`
- [Blob transport](https://github.com/modernrelay/omnigraph/blob/main/crates/omnigraph-server/src/blob_transport.rs): `crates/omnigraph-server/src/blob_transport.rs`

### Other components

- **Agent or UI**

## Connections

- Agent or UI → CLI commands: issues commands (evidence: `README.md`)
- Agent or UI → Graph server: sends requests (evidence: `README.md`)
- CLI commands → Graph client: dispatches commands (evidence: `crates/omnigraph-cli/src/main.rs`)
- Graph client → Graph server: uses HTTP (evidence: `crates/omnigraph-cli/src/client.rs`)
- Graph client → Graph operations: uses embedded engine (evidence: `crates/omnigraph-cli/src/client.rs`)
- Cluster deploy → Schema compiler: applies schemas (evidence: `README.md`)
- Cluster deploy → Cedar policies: publishes policies (evidence: `README.md`)
- Cluster deploy → Graph operations: creates graphs (evidence: `README.md`)
- Graph server → Graph operations: serves graph operations (evidence: `README.md`)
- Graph server → Cedar policies: enforces policies (evidence: `README.md`)
- Graph server → Blob transport: transfers blobs
- Query entry points → Query engine: enters runtime (evidence: `crates/omnigraph/src/exec/query_doors.rs`)
- Query engine → Query compiler: uses compiled queries
- Query compiler → Query planner: supplies query plans
- Query planner → Query engine: plans execution
- Query engine → Staged table storage: reads and writes
- Graph operations → Branch catalog: tracks branch history
- Staged table storage → Lance storage backend: persists tables (evidence: `crates/omnigraph/src/storage_layer.rs`)
- CLI commands → API contracts: uses API contracts
