# lelabdev/rag-ferrite architecture

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

- Interactive diagram: https://gitdiagram.com/lelabdev/rag-ferrite
- Repository: https://github.com/lelabdev/rag-ferrite

## Overview

rag-ferrite is a self-hosted document search and memory service for AI assistants. Users ingest files or text, which are extracted, chunked, optionally enriched, embedded, and indexed in SQLite; assistants then query a hybrid lexical/semantic retrieval pipeline through MCP or REST, with CLI and TUI access also documented. The graph includes ingestion jobs, tags, reranking, and retrieval evaluation as distinct capabilities. Several connections rely on the README or SOURCE INDEX references because their implementations were not excerpted; those links are cited only where documented or indexed.

Main entry points: [`src/pipeline.rs`](https://github.com/lelabdev/rag-ferrite/blob/main/src/pipeline.rs) (Query pipeline), [`src/engine/ingest.rs`](https://github.com/lelabdev/rag-ferrite/blob/main/src/engine/ingest.rs) (Ingest and enrich), [`src/service.rs`](https://github.com/lelabdev/rag-ferrite/blob/main/src/service.rs) (Shared business logic), [`src/engine/search.rs`](https://github.com/lelabdev/rag-ferrite/blob/main/src/engine/search.rs) (Hybrid search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_mcp["MCP tools<br/>[server.rs]"]
  node_rest["REST API<br/>[api.rs]"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_tui["Terminal UI<br/>[ui.rs]"]
end

subgraph group_ingestion["Ingestion"]
  node_queue["Ingestion queue<br/>[ingestion.rs]"]
  node_extract["Text extraction<br/>[extractor.rs]"]
  node_chunk["Parent-child chunking<br/>[chunker.rs]"]
  node_ingest["Ingest and enrich<br/>[ingest.rs]"]
  node_embed["Embedding provider<br/>[embedding.rs]"]
  node_llm["LLM services<br/>[llm.rs]"]
end

subgraph group_retrieval["Retrieval"]
  node_service["Shared business logic<br/>[service.rs]"]
  node_pipeline["Query pipeline<br/>[pipeline.rs]"]
  node_search["Hybrid search<br/>[search.rs]"]
  node_rerank["Optional reranking<br/>[reranker.rs]"]
  node_tags["Tag routing<br/>[tag_routing.rs]"]
end

subgraph group_data["Index and metadata"]
  node_sqlite[("SQLite search index<br/>[sqlite.rs]")]
  node_tagrules["Tag rules<br/>[tag_rules.rs]"]
end

subgraph group_operations["Operations"]
  node_config["Runtime configuration<br/>[config.rs]"]
  node_monitor["Monitor API<br/>[api.rs]"]
  node_benchmark["Retrieval evaluation<br/>[benchmark.rs]"]
end

node_user(("Assistant / user"))
node_providers["Embedding / LLM APIs"]

node_user -->|"uses"| node_mcp
node_user -->|"uses"| node_rest
node_user -->|"uses"| node_cli
node_user -->|"uses"| node_tui
node_mcp -->|"calls"| node_service
node_rest -->|"calls"| node_service
node_cli -.->|"submits jobs"| node_queue
node_tui -->|"uses"| node_monitor
node_monitor -->|"uses client"| node_cli
node_queue -.->|"extracts files"| node_extract
node_queue -->|"dispatches jobs"| node_ingest
node_ingest -->|"chunks content"| node_chunk
node_ingest -->|"embeds chunks"| node_embed
node_ingest -->|"adds context"| node_llm
node_ingest -->|"writes index"| node_sqlite
node_service -->|"submits ingestion"| node_queue
node_service -->|"queries"| node_pipeline
node_pipeline -->|"runs search"| node_search
node_search -->|"embeds query"| node_embed
node_search -->|"retrieves candidates"| node_sqlite
node_search -->|"routes tags"| node_tags
node_tags -->|"loads rules"| node_tagrules
node_pipeline -->|"reranks results"| node_rerank
node_pipeline -->|"expands queries"| node_llm
node_embed -->|"requests embeddings"| node_providers
node_llm -->|"requests completion"| node_providers
node_benchmark -.->|"evaluates retrieval"| node_pipeline
node_service -->|"reads metadata"| node_sqlite
node_config -.->|"configures"| node_pipeline
node_config -.->|"configures"| node_embed

click node_mcp "https://github.com/lelabdev/rag-ferrite/blob/main/src/server.rs"
click node_rest "https://github.com/lelabdev/rag-ferrite/blob/main/src/api.rs"
click node_cli "https://github.com/lelabdev/rag-ferrite/blob/main/src/main.rs"
click node_tui "https://github.com/lelabdev/rag-ferrite/blob/main/src/monitor/ui.rs"
click node_queue "https://github.com/lelabdev/rag-ferrite/blob/main/src/ingestion.rs"
click node_extract "https://github.com/lelabdev/rag-ferrite/blob/main/src/extractor.rs"
click node_chunk "https://github.com/lelabdev/rag-ferrite/blob/main/src/chunker.rs"
click node_ingest "https://github.com/lelabdev/rag-ferrite/blob/main/src/engine/ingest.rs"
click node_embed "https://github.com/lelabdev/rag-ferrite/blob/main/src/embedding.rs"
click node_llm "https://github.com/lelabdev/rag-ferrite/blob/main/src/llm.rs"
click node_service "https://github.com/lelabdev/rag-ferrite/blob/main/src/service.rs"
click node_pipeline "https://github.com/lelabdev/rag-ferrite/blob/main/src/pipeline.rs"
click node_search "https://github.com/lelabdev/rag-ferrite/blob/main/src/engine/search.rs"
click node_rerank "https://github.com/lelabdev/rag-ferrite/blob/main/src/reranker.rs"
click node_tags "https://github.com/lelabdev/rag-ferrite/blob/main/src/engine/tag_routing.rs"
click node_sqlite "https://github.com/lelabdev/rag-ferrite/blob/main/src/storage/sqlite.rs"
click node_tagrules "https://github.com/lelabdev/rag-ferrite/blob/main/src/tag_rules.rs"
click node_config "https://github.com/lelabdev/rag-ferrite/blob/main/src/config.rs"
click node_monitor "https://github.com/lelabdev/rag-ferrite/blob/main/src/monitor/api.rs"
click node_benchmark "https://github.com/lelabdev/rag-ferrite/blob/main/src/engine/benchmark.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_mcp,node_rest,node_cli,node_tui,node_user toneBlue
class node_queue,node_extract,node_chunk,node_ingest,node_embed,node_llm toneAmber
class node_service,node_pipeline,node_search,node_rerank,node_tags,node_providers toneMint
class node_sqlite,node_tagrules toneRose
class node_config,node_monitor,node_benchmark toneIndigo
```

## Components

### User interfaces

- [MCP tools](https://github.com/lelabdev/rag-ferrite/blob/main/src/server.rs): `src/server.rs`
- [REST API](https://github.com/lelabdev/rag-ferrite/blob/main/src/api.rs): `src/api.rs`
- [CLI commands](https://github.com/lelabdev/rag-ferrite/blob/main/src/main.rs): `src/main.rs`
- [Terminal UI](https://github.com/lelabdev/rag-ferrite/blob/main/src/monitor/ui.rs): `src/monitor/ui.rs`

### Ingestion

- [Ingestion queue](https://github.com/lelabdev/rag-ferrite/blob/main/src/ingestion.rs): `src/ingestion.rs`
- [Text extraction](https://github.com/lelabdev/rag-ferrite/blob/main/src/extractor.rs): `src/extractor.rs`
- [Parent-child chunking](https://github.com/lelabdev/rag-ferrite/blob/main/src/chunker.rs): `src/chunker.rs`
- [Ingest and enrich](https://github.com/lelabdev/rag-ferrite/blob/main/src/engine/ingest.rs): `src/engine/ingest.rs`
- [Embedding provider](https://github.com/lelabdev/rag-ferrite/blob/main/src/embedding.rs): `src/embedding.rs`
- [LLM services](https://github.com/lelabdev/rag-ferrite/blob/main/src/llm.rs): `src/llm.rs`

### Retrieval

- [Shared business logic](https://github.com/lelabdev/rag-ferrite/blob/main/src/service.rs): `src/service.rs`
- [Query pipeline](https://github.com/lelabdev/rag-ferrite/blob/main/src/pipeline.rs): `src/pipeline.rs`
- [Hybrid search](https://github.com/lelabdev/rag-ferrite/blob/main/src/engine/search.rs): `src/engine/search.rs`
- [Optional reranking](https://github.com/lelabdev/rag-ferrite/blob/main/src/reranker.rs): `src/reranker.rs`
- [Tag routing](https://github.com/lelabdev/rag-ferrite/blob/main/src/engine/tag_routing.rs): `src/engine/tag_routing.rs`

### Index and metadata

- [SQLite search index](https://github.com/lelabdev/rag-ferrite/blob/main/src/storage/sqlite.rs): `src/storage/sqlite.rs`
- [Tag rules](https://github.com/lelabdev/rag-ferrite/blob/main/src/tag_rules.rs): `src/tag_rules.rs`

### Operations

- [Runtime configuration](https://github.com/lelabdev/rag-ferrite/blob/main/src/config.rs): `src/config.rs`
- [Monitor API](https://github.com/lelabdev/rag-ferrite/blob/main/src/monitor/api.rs): `src/monitor/api.rs`
- [Retrieval evaluation](https://github.com/lelabdev/rag-ferrite/blob/main/src/engine/benchmark.rs): `src/engine/benchmark.rs`

### Other components

- **Assistant / user**
- **Embedding / LLM APIs**

## Connections

- Assistant / user → MCP tools: uses (evidence: `README.md`)
- Assistant / user → REST API: uses (evidence: `README.md`)
- Assistant / user → CLI commands: uses (evidence: `README.md`)
- Assistant / user → Terminal UI: uses (evidence: `README.md`)
- MCP tools → Shared business logic: calls (evidence: `src/server.rs`)
- REST API → Shared business logic: calls (evidence: `src/api.rs`)
- CLI commands → Ingestion queue: submits jobs (evidence: `src/main.rs`)
- Terminal UI → Monitor API: uses (evidence: `src/monitor/ui.rs`)
- Monitor API → CLI commands: uses client (evidence: `src/monitor/api.rs`)
- Ingestion queue → Text extraction: extracts files
- Ingestion queue → Ingest and enrich: dispatches jobs (evidence: `src/ingestion.rs`)
- Ingest and enrich → Parent-child chunking: chunks content (evidence: `src/engine/ingest.rs`)
- Ingest and enrich → Embedding provider: embeds chunks (evidence: `src/engine/ingest.rs`)
- Ingest and enrich → LLM services: adds context (evidence: `src/engine/ingest.rs`)
- Ingest and enrich → SQLite search index: writes index (evidence: `src/engine/ingest.rs`)
- Shared business logic → Ingestion queue: submits ingestion (evidence: `src/ingestion.rs`)
- Shared business logic → Query pipeline: queries (evidence: `src/service.rs`)
- Query pipeline → Hybrid search: runs search (evidence: `src/engine/search.rs`)
- Hybrid search → Embedding provider: embeds query (evidence: `src/engine/search.rs`)
- Hybrid search → SQLite search index: retrieves candidates (evidence: `src/engine/search.rs`)
- Hybrid search → Tag routing: routes tags (evidence: `src/engine/search.rs`)
- Tag routing → Tag rules: loads rules (evidence: `src/engine/tag_routing.rs`)
- Query pipeline → Optional reranking: reranks results (evidence: `src/pipeline.rs`)
- Query pipeline → LLM services: expands queries (evidence: `src/pipeline.rs`)
- Embedding provider → Embedding / LLM APIs: requests embeddings (evidence: `README.md`)
- LLM services → Embedding / LLM APIs: requests completion (evidence: `src/llm.rs`)
- Retrieval evaluation → Query pipeline: evaluates retrieval
- Shared business logic → SQLite search index: reads metadata (evidence: `src/service.rs`)
- Runtime configuration → Query pipeline: configures (evidence: `src/pipeline.rs`)
- Runtime configuration → Embedding provider: configures
