# arihntk/raggit architecture

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

- Interactive diagram: https://gitdiagram.com/arihntk/raggit
- Repository: https://github.com/arihntk/raggit

## Overview

raggit is a document-indexing and retrieval-augmented question-answering system. Users submit documents through the CLI, HTTP API, watcher, or optional MCP interface; ingestion parses, chunks, cleans, protects, embeds, and stores them. Queries are sanitized and optionally rewritten, searched with hybrid retrieval, fused and reranked, then augmented into cited answers with safety checks. PostgreSQL and Qdrant hold metadata and vectors; storage adapters and LLM providers supply external services. The README documents the main pipelines; source-index references support selected internal wiring, while some API, MCP, and evaluation details are not sampled.

Main entry points: [`raggit/ingestion/indexer.py`](https://github.com/arihntk/raggit/blob/main/raggit/ingestion/indexer.py) (Indexing orchestrator), [`raggit/retrieval/engine.py`](https://github.com/arihntk/raggit/blob/main/raggit/retrieval/engine.py) (Query retrieval engine), [`raggit/cli/main.py`](https://github.com/arihntk/raggit/blob/main/raggit/cli/main.py) (CLI), [`raggit/api/server.py`](https://github.com/arihntk/raggit/blob/main/raggit/api/server.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[main.py]"]
  node_http["HTTP API<br/>[server.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_watcher["Storage watcher<br/>[watcher.py]"]
end

subgraph group_ingestion["Document ingestion"]
  node_indexer["Indexing orchestrator<br/>[indexer.py]"]
  node_storage["Storage adapters<br/>[factory.py]"]
  node_parser["Format parser<br/>[parser.py]"]
  node_chunker["Chunking and cleaning<br/>[chunker.py]"]
  node_protection["PII and injection safeguards<br/>[injection.py]"]
  node_embedder["Embedder<br/>[embedder.py]"]
end

subgraph group_retrieval["Retrieval and answers"]
  node_query["Query retrieval engine<br/>[engine.py]"]
  node_querytools["Query rewriting and sanitizing<br/>[rewrite.py]"]
  node_fusion["Rank fusion and reranking<br/>[rrf.py]"]
  node_augmenter["Answer augmentation<br/>[augmenter.py]"]
  node_llm["LLM providers<br/>[factory.py]"]
end

subgraph group_state["State and integrations"]
  node_api_models["Shared domain models<br/>[models.py]"]
  node_audit["Audit logging<br/>[audit.py]"]
  node_postgres[("PostgreSQL")]
  node_vector[("Qdrant vector store<br/>[vector.py]")]
end

subgraph group_evaluation["Evaluation"]
  node_eval["Evaluation framework<br/>[pipeline.py]"]
  node_eval_models["Evaluation models<br/>[models.py]"]
end

node_user(("User"))
node_qdrant_service[("Qdrant service")]

node_user -->|"runs commands"| node_cli
node_user -->|"sends requests"| node_http
node_user -.->|"connects optionally"| node_mcp
node_watcher -->|"watches sources"| node_storage
node_watcher -->|"triggers indexing"| node_indexer
node_cli -->|"starts ingestion"| node_indexer
node_http -->|"triggers ingestion"| node_indexer
node_mcp -->|"offers ingestion"| node_indexer
node_indexer -->|"reads documents"| node_storage
node_indexer -->|"parses files"| node_parser
node_indexer -->|"chunks and cleans"| node_chunker
node_indexer -->|"hardens content"| node_protection
node_indexer -->|"embeds chunks"| node_embedder
node_indexer -->|"stores metadata"| node_postgres
node_indexer -->|"writes vectors"| node_vector
node_vector -->|"persists vectors"| node_qdrant_service
node_cli -->|"runs queries"| node_query
node_http -->|"serves queries"| node_query
node_mcp -->|"offers query tool"| node_query
node_query -->|"sanitizes and rewrites"| node_querytools
node_query -->|"searches BM25"| node_postgres
node_query -->|"searches semantically"| node_vector
node_query -->|"fuses and reranks"| node_fusion
node_query -->|"provides retrieved context"| node_augmenter
node_augmenter -->|"generates answer"| node_llm
node_augmenter -->|"hardens context"| node_protection
node_augmenter -->|"checks groundedness"| node_query
node_indexer -->|"audits ingestion"| node_audit
node_query -->|"audits queries"| node_audit
node_audit -->|"writes audit events"| node_postgres
node_cli -->|"runs evaluations"| node_eval
node_http -->|"exposes evaluations"| node_eval
node_eval -->|"scores datasets"| node_eval_models
node_eval -->|"evaluates retrieval"| node_query
node_api_models -.->|"defines query results"| node_query

click node_cli "https://github.com/arihntk/raggit/blob/main/raggit/cli/main.py"
click node_http "https://github.com/arihntk/raggit/blob/main/raggit/api/server.py"
click node_mcp "https://github.com/arihntk/raggit/blob/main/raggit/mcp_server.py"
click node_watcher "https://github.com/arihntk/raggit/blob/main/raggit/core/watcher.py"
click node_indexer "https://github.com/arihntk/raggit/blob/main/raggit/ingestion/indexer.py"
click node_storage "https://github.com/arihntk/raggit/blob/main/raggit/storage/factory.py"
click node_parser "https://github.com/arihntk/raggit/blob/main/raggit/ingestion/parser.py"
click node_chunker "https://github.com/arihntk/raggit/blob/main/raggit/ingestion/chunker.py"
click node_protection "https://github.com/arihntk/raggit/blob/main/raggit/ingestion/injection.py"
click node_embedder "https://github.com/arihntk/raggit/blob/main/raggit/ingestion/embedder.py"
click node_query "https://github.com/arihntk/raggit/blob/main/raggit/retrieval/engine.py"
click node_querytools "https://github.com/arihntk/raggit/blob/main/raggit/retrieval/rewrite.py"
click node_fusion "https://github.com/arihntk/raggit/blob/main/raggit/retrieval/rrf.py"
click node_augmenter "https://github.com/arihntk/raggit/blob/main/raggit/llm/augmenter.py"
click node_llm "https://github.com/arihntk/raggit/blob/main/raggit/llm/factory.py"
click node_api_models "https://github.com/arihntk/raggit/blob/main/raggit/api/models.py"
click node_audit "https://github.com/arihntk/raggit/blob/main/raggit/core/audit.py"
click node_vector "https://github.com/arihntk/raggit/blob/main/raggit/db/vector.py"
click node_eval "https://github.com/arihntk/raggit/blob/main/raggit/eval/pipeline.py"
click node_eval_models "https://github.com/arihntk/raggit/blob/main/raggit/eval/models.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_cli,node_http,node_mcp,node_watcher,node_user toneBlue
class node_indexer,node_storage,node_parser,node_chunker,node_protection,node_embedder,node_qdrant_service toneAmber
class node_query,node_querytools,node_fusion,node_augmenter,node_llm toneMint
class node_api_models,node_audit,node_postgres,node_vector toneRose
class node_eval,node_eval_models toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/arihntk/raggit/blob/main/raggit/cli/main.py): `raggit/cli/main.py`
- [HTTP API](https://github.com/arihntk/raggit/blob/main/raggit/api/server.py): `raggit/api/server.py`
- [MCP server](https://github.com/arihntk/raggit/blob/main/raggit/mcp_server.py): `raggit/mcp_server.py`
- [Storage watcher](https://github.com/arihntk/raggit/blob/main/raggit/core/watcher.py): `raggit/core/watcher.py`

### Document ingestion

- [Indexing orchestrator](https://github.com/arihntk/raggit/blob/main/raggit/ingestion/indexer.py): `raggit/ingestion/indexer.py`
- [Storage adapters](https://github.com/arihntk/raggit/blob/main/raggit/storage/factory.py): `raggit/storage/factory.py`
- [Format parser](https://github.com/arihntk/raggit/blob/main/raggit/ingestion/parser.py): `raggit/ingestion/parser.py`
- [Chunking and cleaning](https://github.com/arihntk/raggit/blob/main/raggit/ingestion/chunker.py): `raggit/ingestion/chunker.py`
- [PII and injection safeguards](https://github.com/arihntk/raggit/blob/main/raggit/ingestion/injection.py): `raggit/ingestion/injection.py`
- [Embedder](https://github.com/arihntk/raggit/blob/main/raggit/ingestion/embedder.py): `raggit/ingestion/embedder.py`

### Retrieval and answers

- [Query retrieval engine](https://github.com/arihntk/raggit/blob/main/raggit/retrieval/engine.py): `raggit/retrieval/engine.py`
- [Query rewriting and sanitizing](https://github.com/arihntk/raggit/blob/main/raggit/retrieval/rewrite.py): `raggit/retrieval/rewrite.py`
- [Rank fusion and reranking](https://github.com/arihntk/raggit/blob/main/raggit/retrieval/rrf.py): `raggit/retrieval/rrf.py`
- [Answer augmentation](https://github.com/arihntk/raggit/blob/main/raggit/llm/augmenter.py): `raggit/llm/augmenter.py`
- [LLM providers](https://github.com/arihntk/raggit/blob/main/raggit/llm/factory.py): `raggit/llm/factory.py`

### State and integrations

- [Shared domain models](https://github.com/arihntk/raggit/blob/main/raggit/api/models.py): `raggit/api/models.py`
- [Audit logging](https://github.com/arihntk/raggit/blob/main/raggit/core/audit.py): `raggit/core/audit.py`
- **PostgreSQL**
- [Qdrant vector store](https://github.com/arihntk/raggit/blob/main/raggit/db/vector.py): `raggit/db/vector.py`

### Evaluation

- [Evaluation framework](https://github.com/arihntk/raggit/blob/main/raggit/eval/pipeline.py): `raggit/eval/pipeline.py`
- [Evaluation models](https://github.com/arihntk/raggit/blob/main/raggit/eval/models.py): `raggit/eval/models.py`

### Other components

- **User**
- **Qdrant service**

## Connections

- User → CLI: runs commands
- User → HTTP API: sends requests
- User → MCP server: connects optionally
- Storage watcher → Storage adapters: watches sources (evidence: `raggit/core/watcher.py`)
- Storage watcher → Indexing orchestrator: triggers indexing (evidence: `raggit/core/watcher.py`)
- CLI → Indexing orchestrator: starts ingestion
- HTTP API → Indexing orchestrator: triggers ingestion (evidence: `raggit/api/server.py`)
- MCP server → Indexing orchestrator: offers ingestion (evidence: `raggit/mcp_server.py`)
- Indexing orchestrator → Storage adapters: reads documents (evidence: `raggit/ingestion/indexer.py`)
- Indexing orchestrator → Format parser: parses files (evidence: `raggit/ingestion/indexer.py`)
- Indexing orchestrator → Chunking and cleaning: chunks and cleans (evidence: `raggit/ingestion/indexer.py`)
- Indexing orchestrator → PII and injection safeguards: hardens content (evidence: `raggit/ingestion/indexer.py`)
- Indexing orchestrator → Embedder: embeds chunks (evidence: `raggit/ingestion/indexer.py`)
- Indexing orchestrator → PostgreSQL: stores metadata
- Indexing orchestrator → Qdrant vector store: writes vectors (evidence: `raggit/ingestion/indexer.py`)
- Qdrant vector store → Qdrant service: persists vectors (evidence: `raggit/db/vector.py`)
- CLI → Query retrieval engine: runs queries
- HTTP API → Query retrieval engine: serves queries (evidence: `raggit/api/server.py`)
- MCP server → Query retrieval engine: offers query tool (evidence: `raggit/mcp_server.py`)
- Query retrieval engine → Query rewriting and sanitizing: sanitizes and rewrites (evidence: `raggit/retrieval/engine.py`)
- Query retrieval engine → PostgreSQL: searches BM25
- Query retrieval engine → Qdrant vector store: searches semantically (evidence: `raggit/retrieval/engine.py`)
- Query retrieval engine → Rank fusion and reranking: fuses and reranks (evidence: `raggit/retrieval/engine.py`)
- Query retrieval engine → Answer augmentation: provides retrieved context (evidence: `raggit/cli/query_cmd.py`)
- Answer augmentation → LLM providers: generates answer (evidence: `raggit/llm/augmenter.py`)
- Answer augmentation → PII and injection safeguards: hardens context (evidence: `raggit/llm/augmenter.py`)
- Answer augmentation → Query retrieval engine: checks groundedness
- Indexing orchestrator → Audit logging: audits ingestion (evidence: `raggit/ingestion/indexer.py`)
- Query retrieval engine → Audit logging: audits queries (evidence: `raggit/retrieval/engine.py`)
- Audit logging → PostgreSQL: writes audit events (evidence: `raggit/core/audit.py`)
- CLI → Evaluation framework: runs evaluations (evidence: `raggit/cli/main.py`)
- HTTP API → Evaluation framework: exposes evaluations (evidence: `raggit/api/server.py`)
- Evaluation framework → Evaluation models: scores datasets (evidence: `raggit/eval/pipeline.py`)
- Evaluation framework → Query retrieval engine: evaluates retrieval (evidence: `raggit/eval/pipeline.py`)
- Shared domain models → Query retrieval engine: defines query results (evidence: `raggit/retrieval/engine.py`)
