# mileschintw/rust-lancedb-graphrag architecture

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

- Interactive diagram: https://gitdiagram.com/mileschintw/rust-lancedb-graphrag
- Repository: https://github.com/mileschintw/rust-lancedb-graphrag
- Video tour (about a minute): https://gitdiagram.com/mileschintw/rust-lancedb-graphrag/video

## Overview

Lancet is a RAG/GraphRAG platform: clients submit documents and questions through a Go control plane, which coordinates a Rust data plane for ingestion and answer generation. The query path combines dense and BM25 retrieval, fusion, optional reranking and graph context, then assembles cited answers and streams workflow events. A separate Python evaluation harness exercises the service and measures quality, latency, and preregistered gates. Edges reflect README statements and shown source references; some internal calls and storage wiring are not visible in the supplied excerpts, so they are omitted rather than inferred.

Main entry points: [`engine/src/service.rs`](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/service.rs) (Engine Service), [`gateway/main.go`](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/gateway/main.go) (HTTP API), [`engine/src/ingest.rs`](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/ingest.rs) (Document Ingestion), [`engine/src/workflow/nodes/retrieve.rs`](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/workflow/nodes/retrieve.rs) (Retrieval Stage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Go Control Plane"]
  node_gateway_api["HTTP API<br/>[main.go]"]
  node_engine_rpc["Engine Client<br/>[engineclient.go]"]
  node_gateway_store[("Document Store")]
  node_sse["SSE Events<br/>[sse.go]"]
end

subgraph group_engine["Rust Data Plane"]
  node_grpc["gRPC Contract<br/>[lancet.proto]"]
  node_engine_service["Engine Service<br/>[service.rs]"]
  node_ingestion["Document Ingestion<br/>[ingest.rs]"]
  node_chunker["Chunking<br/>[mod.rs]"]
  node_lancedb[("LanceDB Access<br/>[mod.rs]")]
  node_workflow["Workflow Runner<br/>[runner.rs]"]
  node_retrieve_node["Retrieval Stage<br/>[retrieve.rs]"]
  node_retrieval["Hybrid Retrieval<br/>[mod.rs]"]
  node_rerank["Reranking<br/>[mod.rs]"]
  node_graph["Knowledge Graph<br/>[mod.rs]"]
  node_prompt["Prompt Assembly<br/>[prompt.rs]"]
  node_generation["Answer Generation<br/>[mod.rs]"]
end

subgraph group_evaluation["Evaluation Harness"]
  node_eval_client["Service Eval Client<br/>[client.py]"]
  node_eval_arms["Evaluation Arms<br/>[arms.py]"]
  node_eval_score["Scoring &amp; Reports<br/>[score.py]"]
  node_eval_metrics["Metrics &amp; Statistics<br/>[metrics.py]"]
  node_eval_thresholds["Evaluation Gates<br/>[thresholds.py]"]
end

node_client(("User / Client"))
node_openrouter["OpenRouter"]

node_client -->|"submits queries"| node_gateway_api
node_gateway_api -->|"dispatches RPC"| node_engine_rpc
node_gateway_api -->|"reads and writes"| node_gateway_store
node_gateway_api -->|"streams events"| node_sse
node_engine_rpc -->|"uses contract"| node_grpc
node_engine_service -->|"implements service"| node_grpc
node_engine_service -->|"handles ingestion"| node_ingestion
node_ingestion -->|"chunks documents"| node_chunker
node_ingestion -->|"mutates indexes"| node_lancedb
node_engine_service -->|"queries storage"| node_lancedb
node_engine_service -->|"runs queries"| node_workflow
node_workflow -->|"dispatches stage"| node_retrieve_node
node_retrieve_node -->|"retrieves candidates"| node_retrieval
node_retrieve_node -->|"reranks candidates"| node_rerank
node_engine_service -->|"provides graph context"| node_graph
node_engine_service -->|"generates answer"| node_generation
node_generation -->|"assembles evidence prompt"| node_prompt
node_generation -->|"calls provider"| node_openrouter
node_rerank -->|"calls provider"| node_openrouter
node_eval_client -->|"queries endpoint"| node_gateway_api
node_eval_arms -->|"runs service arms"| node_eval_client
node_eval_arms -->|"records measurements"| node_eval_score
node_eval_score -->|"computes metrics"| node_eval_metrics
node_eval_score -->|"checks gates"| node_eval_thresholds

click node_gateway_api "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/gateway/main.go"
click node_engine_rpc "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/gateway/internal/engineclient/engineclient.go"
click node_gateway_store "https://github.com/mileschintw/rust-lancedb-graphrag/tree/main/gateway/db"
click node_sse "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/gateway/internal/sse/sse.go"
click node_grpc "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/proto/lancet/v1/lancet.proto"
click node_engine_service "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/service.rs"
click node_ingestion "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/ingest.rs"
click node_chunker "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/chunker/mod.rs"
click node_lancedb "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/db/mod.rs"
click node_workflow "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/workflow/runner.rs"
click node_retrieve_node "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/workflow/nodes/retrieve.rs"
click node_retrieval "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/retrieval/mod.rs"
click node_rerank "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/rerank/mod.rs"
click node_graph "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/graph/mod.rs"
click node_prompt "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/prompt.rs"
click node_generation "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/generation/mod.rs"
click node_eval_client "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/eval/src/lancet_eval/client.py"
click node_eval_arms "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/eval/src/lancet_eval/arms.py"
click node_eval_score "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/eval/src/lancet_eval/score.py"
click node_eval_metrics "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/eval/src/lancet_eval/metrics.py"
click node_eval_thresholds "https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/eval/src/lancet_eval/thresholds.py"

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_gateway_api,node_engine_rpc,node_gateway_store,node_sse,node_client toneBlue
class node_grpc,node_engine_service,node_ingestion,node_chunker,node_lancedb,node_workflow,node_retrieve_node,node_retrieval,node_rerank,node_graph,node_prompt,node_generation toneAmber
class node_eval_client,node_eval_arms,node_eval_score,node_eval_metrics,node_eval_thresholds,node_openrouter toneMint
```

## Components

### Go Control Plane

- [HTTP API](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/gateway/main.go): `gateway/main.go`
- [Engine Client](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/gateway/internal/engineclient/engineclient.go): `gateway/internal/engineclient/engineclient.go`
- [Document Store](https://github.com/mileschintw/rust-lancedb-graphrag/tree/main/gateway/db): `gateway/db`
- [SSE Events](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/gateway/internal/sse/sse.go): `gateway/internal/sse/sse.go`

### Rust Data Plane

- [gRPC Contract](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/proto/lancet/v1/lancet.proto): `proto/lancet/v1/lancet.proto`
- [Engine Service](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/service.rs): `engine/src/service.rs`
- [Document Ingestion](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/ingest.rs): `engine/src/ingest.rs`
- [Chunking](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/chunker/mod.rs): `engine/src/chunker/mod.rs`
- [LanceDB Access](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/db/mod.rs): `engine/src/db/mod.rs`
- [Workflow Runner](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/workflow/runner.rs): `engine/src/workflow/runner.rs`
- [Retrieval Stage](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/workflow/nodes/retrieve.rs): `engine/src/workflow/nodes/retrieve.rs`
- [Hybrid Retrieval](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/retrieval/mod.rs): `engine/src/retrieval/mod.rs`
- [Reranking](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/rerank/mod.rs): `engine/src/rerank/mod.rs`
- [Knowledge Graph](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/graph/mod.rs): `engine/src/graph/mod.rs`
- [Prompt Assembly](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/prompt.rs): `engine/src/prompt.rs`
- [Answer Generation](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/engine/src/generation/mod.rs): `engine/src/generation/mod.rs`

### Evaluation Harness

- [Service Eval Client](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/eval/src/lancet_eval/client.py): `eval/src/lancet_eval/client.py`
- [Evaluation Arms](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/eval/src/lancet_eval/arms.py): `eval/src/lancet_eval/arms.py`
- [Scoring & Reports](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/eval/src/lancet_eval/score.py): `eval/src/lancet_eval/score.py`
- [Metrics & Statistics](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/eval/src/lancet_eval/metrics.py): `eval/src/lancet_eval/metrics.py`
- [Evaluation Gates](https://github.com/mileschintw/rust-lancedb-graphrag/blob/main/eval/src/lancet_eval/thresholds.py): `eval/src/lancet_eval/thresholds.py`

### Other components

- **User / Client**
- **OpenRouter**

## Connections

- User / Client → HTTP API: submits queries
- HTTP API → Engine Client: dispatches RPC (evidence: `gateway/main.go`)
- HTTP API → Document Store: reads and writes (evidence: `gateway/main.go`)
- HTTP API → SSE Events: streams events (evidence: `gateway/main.go`)
- Engine Client → gRPC Contract: uses contract (evidence: `gateway/internal/engineclient/engineclient.go`)
- Engine Service → gRPC Contract: implements service (evidence: `engine/src/service.rs`)
- Engine Service → Document Ingestion: handles ingestion (evidence: `engine/src/service.rs`)
- Document Ingestion → Chunking: chunks documents (evidence: `engine/src/ingest.rs`)
- Document Ingestion → LanceDB Access: mutates indexes (evidence: `engine/src/ingest.rs`)
- Engine Service → LanceDB Access: queries storage (evidence: `engine/src/service.rs`)
- Engine Service → Workflow Runner: runs queries (evidence: `engine/src/service.rs`)
- Workflow Runner → Retrieval Stage: dispatches stage (evidence: `engine/src/workflow/nodes/retrieve.rs`)
- Retrieval Stage → Hybrid Retrieval: retrieves candidates (evidence: `engine/src/workflow/nodes/retrieve.rs`)
- Retrieval Stage → Reranking: reranks candidates (evidence: `engine/src/workflow/nodes/retrieve.rs`)
- Engine Service → Knowledge Graph: provides graph context (evidence: `engine/src/service.rs`)
- Engine Service → Answer Generation: generates answer (evidence: `engine/src/service.rs`)
- Answer Generation → Prompt Assembly: assembles evidence prompt (evidence: `engine/src/generation/mod.rs`)
- Answer Generation → OpenRouter: calls provider
- Reranking → OpenRouter: calls provider
- Service Eval Client → HTTP API: queries endpoint (evidence: `eval/src/lancet_eval/client.py`)
- Evaluation Arms → Service Eval Client: runs service arms (evidence: `eval/src/lancet_eval/arms.py`)
- Evaluation Arms → Scoring & Reports: records measurements (evidence: `eval/src/lancet_eval/arms.py`)
- Scoring & Reports → Metrics & Statistics: computes metrics (evidence: `eval/src/lancet_eval/score.py`)
- Scoring & Reports → Evaluation Gates: checks gates (evidence: `eval/src/lancet_eval/score.py`)
