# milihwork/document_rag architecture

> Architecture diagram of the GitHub repository milihwork/document_rag, 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/milihwork/document_rag
- Repository: https://github.com/milihwork/document_rag

## Overview

Document RAG is a local-first platform for ingesting PDFs or raw text and answering questions with document-grounded responses and source attribution. Users enter through the React UI and Gateway, or AI agents through MCP tools. Ingestion extracts and chunks text, then embeds and stores it; question answering coordinates safeguards, embedding, retrieval, optional rewriting and reranking, ML analysis, and LLM generation. The README documents backend capabilities and integrations beyond the sampled excerpts; edges for those are cited to the README, while uncertain internal wiring is omitted.

Main entry points: [`backend/services/rag/app/main.py`](https://github.com/milihwork/document_rag/blob/main/backend/services/rag/app/main.py) (RAG orchestration), [`backend/services/ingestion/app/main.py`](https://github.com/milihwork/document_rag/blob/main/backend/services/ingestion/app/main.py) (Ingestion API), [`mcp_service/rag_tools.py`](https://github.com/milihwork/document_rag/blob/main/mcp_service/rag_tools.py) (MCP tools), [`backend/services/ml/app/components/factory.py`](https://github.com/milihwork/document_rag/blob/main/backend/services/ml/app/components/factory.py) (ML component factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_frontend["React UI<br/>[App.tsx]"]
  node_frontend_api["UI API client<br/>[api.ts]"]
  node_gateway["Express Gateway<br/>[app.ts]"]
  node_mcp["MCP tools<br/>[rag_tools.py]"]
end

subgraph group_services["Backend services"]
  node_ingestion["Ingestion API<br/>[main.py]"]
  node_embedding["Embedding API<br/>[main.py]"]
  node_retrieval["Retrieval API<br/>[main.py]"]
  node_rag["RAG orchestration<br/>[main.py]"]
  node_ml["ML analysis API<br/>[main.py]"]
end

subgraph group_quality["Quality and safety"]
  node_ml_factory["ML component factory<br/>[factory.py]"]
  node_injection["Injection detector"]
  node_query_classifier["Query classifier"]
  node_retrieval_scorer["Retrieval scorer"]
  node_document_classifier["Document classifier"]
  node_safeguard["Input/output safeguards<br/>[basic_guard.py]"]
  node_rewriter["Query rewriting<br/>[llm_rewriter.py]"]
  node_reranker["BGE reranking<br/>[bge_reranker.py]"]
end

subgraph group_shared["Shared processing"]
  node_pdf["PDF extraction<br/>[pdf_parser.py]"]
  node_chunker["Text chunking<br/>[chunker.py]"]
end

subgraph group_providers["AI and storage providers"]
  node_vector_store[("Vector database")]
  node_llm["LLM provider"]
end

node_user(("Document user"))
node_agent(("AI agent"))

node_user -->|"asks or uploads"| node_frontend
node_frontend -->|"calls API client"| node_frontend_api
node_frontend_api -->|"sends requests"| node_gateway
node_user -->|"uses API"| node_gateway
node_agent -->|"invokes tools"| node_mcp
node_mcp -->|"posts text"| node_ingestion
node_mcp -->|"embeds search query"| node_embedding
node_mcp -->|"searches chunks"| node_retrieval
node_mcp -->|"requests answers"| node_rag
node_gateway -->|"proxies PDF upload"| node_ingestion
node_gateway -->|"proxies chat"| node_rag
node_ingestion -->|"extracts PDF text"| node_pdf
node_ingestion -->|"chunks text"| node_chunker
node_ingestion -->|"requests embeddings"| node_embedding
node_ingestion -->|"upserts points"| node_retrieval
node_ingestion -->|"classifies documents"| node_ml
node_embedding -.->|"uses local model"| node_llm
node_retrieval -->|"searches and stores vectors"| node_vector_store
node_rag -->|"embeds question"| node_embedding
node_rag -->|"searches chunks"| node_retrieval
node_rag -->|"analyzes and scores"| node_ml
node_rag -->|"validates input"| node_safeguard
node_rag -->|"rewrites query"| node_rewriter
node_rag -->|"reranks chunks"| node_reranker
node_rag -->|"generates answer"| node_llm
node_ml -->|"gets analysis components"| node_ml_factory
node_ml_factory -->|"creates detector"| node_injection
node_ml_factory -->|"creates classifier"| node_query_classifier
node_ml_factory -->|"creates scorer"| node_retrieval_scorer
node_ml_factory -->|"creates classifier"| node_document_classifier
node_ml -.->|"uses completion backend"| node_llm
node_safeguard -.->|"optional analysis"| node_llm

click node_frontend "https://github.com/milihwork/document_rag/blob/main/frontend/src/App.tsx"
click node_frontend_api "https://github.com/milihwork/document_rag/blob/main/frontend/src/api.ts"
click node_gateway "https://github.com/milihwork/document_rag/blob/main/backend/services/gateway/src/app.ts"
click node_mcp "https://github.com/milihwork/document_rag/blob/main/mcp_service/rag_tools.py"
click node_ingestion "https://github.com/milihwork/document_rag/blob/main/backend/services/ingestion/app/main.py"
click node_pdf "https://github.com/milihwork/document_rag/blob/main/backend/shared/pdf_parser.py"
click node_chunker "https://github.com/milihwork/document_rag/blob/main/backend/shared/chunker.py"
click node_embedding "https://github.com/milihwork/document_rag/blob/main/backend/services/embedding/app/main.py"
click node_retrieval "https://github.com/milihwork/document_rag/blob/main/backend/services/retrieval/app/main.py"
click node_rag "https://github.com/milihwork/document_rag/blob/main/backend/services/rag/app/main.py"
click node_ml "https://github.com/milihwork/document_rag/blob/main/backend/services/ml/app/main.py"
click node_ml_factory "https://github.com/milihwork/document_rag/blob/main/backend/services/ml/app/components/factory.py"
click node_injection "https://github.com/milihwork/document_rag/blob/main/backend/services/ml/app/components/injection_detector.py"
click node_query_classifier "https://github.com/milihwork/document_rag/blob/main/backend/services/ml/app/components/query_classifier.py"
click node_retrieval_scorer "https://github.com/milihwork/document_rag/blob/main/backend/services/ml/app/components/retrieval_scorer.py"
click node_document_classifier "https://github.com/milihwork/document_rag/blob/main/backend/services/ml/app/components/document_classifier.py"
click node_safeguard "https://github.com/milihwork/document_rag/blob/main/backend/services/safeguard/basic_guard.py"
click node_rewriter "https://github.com/milihwork/document_rag/blob/main/backend/shared/query_rewriter/llm_rewriter.py"
click node_reranker "https://github.com/milihwork/document_rag/blob/main/backend/shared/reranker/bge_reranker.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_frontend,node_frontend_api,node_gateway,node_mcp,node_user toneBlue
class node_ingestion,node_embedding,node_retrieval,node_rag,node_ml toneAmber
class node_ml_factory,node_injection,node_query_classifier,node_retrieval_scorer,node_document_classifier,node_safeguard,node_rewriter,node_reranker toneMint
class node_pdf,node_chunker toneRose
class node_vector_store,node_llm,node_agent toneIndigo
```

## Components

### User interfaces

- [React UI](https://github.com/milihwork/document_rag/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [UI API client](https://github.com/milihwork/document_rag/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Express Gateway](https://github.com/milihwork/document_rag/blob/main/backend/services/gateway/src/app.ts): `backend/services/gateway/src/app.ts`
- [MCP tools](https://github.com/milihwork/document_rag/blob/main/mcp_service/rag_tools.py): `mcp_service/rag_tools.py`

### Backend services

- [Ingestion API](https://github.com/milihwork/document_rag/blob/main/backend/services/ingestion/app/main.py): `backend/services/ingestion/app/main.py`
- [Embedding API](https://github.com/milihwork/document_rag/blob/main/backend/services/embedding/app/main.py): `backend/services/embedding/app/main.py`
- [Retrieval API](https://github.com/milihwork/document_rag/blob/main/backend/services/retrieval/app/main.py): `backend/services/retrieval/app/main.py`
- [RAG orchestration](https://github.com/milihwork/document_rag/blob/main/backend/services/rag/app/main.py): `backend/services/rag/app/main.py`
- [ML analysis API](https://github.com/milihwork/document_rag/blob/main/backend/services/ml/app/main.py): `backend/services/ml/app/main.py`

### Quality and safety

- [ML component factory](https://github.com/milihwork/document_rag/blob/main/backend/services/ml/app/components/factory.py): `backend/services/ml/app/components/factory.py`
- [Injection detector](https://github.com/milihwork/document_rag/blob/main/backend/services/ml/app/components/injection_detector.py): `backend/services/ml/app/components/injection_detector.py`
- [Query classifier](https://github.com/milihwork/document_rag/blob/main/backend/services/ml/app/components/query_classifier.py): `backend/services/ml/app/components/query_classifier.py`
- [Retrieval scorer](https://github.com/milihwork/document_rag/blob/main/backend/services/ml/app/components/retrieval_scorer.py): `backend/services/ml/app/components/retrieval_scorer.py`
- [Document classifier](https://github.com/milihwork/document_rag/blob/main/backend/services/ml/app/components/document_classifier.py): `backend/services/ml/app/components/document_classifier.py`
- [Input/output safeguards](https://github.com/milihwork/document_rag/blob/main/backend/services/safeguard/basic_guard.py): `backend/services/safeguard/basic_guard.py`
- [Query rewriting](https://github.com/milihwork/document_rag/blob/main/backend/shared/query_rewriter/llm_rewriter.py): `backend/shared/query_rewriter/llm_rewriter.py`
- [BGE reranking](https://github.com/milihwork/document_rag/blob/main/backend/shared/reranker/bge_reranker.py): `backend/shared/reranker/bge_reranker.py`

### Shared processing

- [PDF extraction](https://github.com/milihwork/document_rag/blob/main/backend/shared/pdf_parser.py): `backend/shared/pdf_parser.py`
- [Text chunking](https://github.com/milihwork/document_rag/blob/main/backend/shared/chunker.py): `backend/shared/chunker.py`

### AI and storage providers

- **Vector database**
- **LLM provider**

### Other components

- **Document user**
- **AI agent**

## Connections

- Document user → React UI: asks or uploads (evidence: `README.md`)
- React UI → UI API client: calls API client (evidence: `frontend/src/App.tsx`)
- UI API client → Express Gateway: sends requests (evidence: `README.md`)
- Document user → Express Gateway: uses API (evidence: `README.md`)
- AI agent → MCP tools: invokes tools (evidence: `README.md`)
- MCP tools → Ingestion API: posts text (evidence: `mcp_service/rag_tools.py`)
- MCP tools → Embedding API: embeds search query (evidence: `mcp_service/rag_tools.py`)
- MCP tools → Retrieval API: searches chunks (evidence: `mcp_service/rag_tools.py`)
- MCP tools → RAG orchestration: requests answers (evidence: `mcp_service/rag_tools.py`)
- Express Gateway → Ingestion API: proxies PDF upload (evidence: `backend/services/gateway/src/app.ts`)
- Express Gateway → RAG orchestration: proxies chat (evidence: `backend/services/gateway/src/app.ts`)
- Ingestion API → PDF extraction: extracts PDF text (evidence: `backend/services/ingestion/app/main.py`)
- Ingestion API → Text chunking: chunks text (evidence: `backend/services/ingestion/app/main.py`)
- Ingestion API → Embedding API: requests embeddings (evidence: `backend/services/ingestion/app/main.py`)
- Ingestion API → Retrieval API: upserts points (evidence: `backend/services/ingestion/app/main.py`)
- Ingestion API → ML analysis API: classifies documents (evidence: `backend/services/ingestion/app/main.py`)
- Embedding API → LLM provider: uses local model (evidence: `README.md`)
- Retrieval API → Vector database: searches and stores vectors (evidence: `README.md`)
- RAG orchestration → Embedding API: embeds question (evidence: `backend/services/rag/app/main.py`)
- RAG orchestration → Retrieval API: searches chunks (evidence: `backend/services/rag/app/main.py`)
- RAG orchestration → ML analysis API: analyzes and scores (evidence: `backend/services/rag/app/main.py`)
- RAG orchestration → Input/output safeguards: validates input (evidence: `backend/services/rag/app/main.py`)
- RAG orchestration → Query rewriting: rewrites query (evidence: `backend/services/rag/app/main.py`)
- RAG orchestration → BGE reranking: reranks chunks (evidence: `backend/services/rag/app/main.py`)
- RAG orchestration → LLM provider: generates answer (evidence: `README.md`)
- ML analysis API → ML component factory: gets analysis components (evidence: `backend/services/ml/app/main.py`)
- ML component factory → Injection detector: creates detector (evidence: `backend/services/ml/app/components/factory.py`)
- ML component factory → Query classifier: creates classifier (evidence: `backend/services/ml/app/components/factory.py`)
- ML component factory → Retrieval scorer: creates scorer (evidence: `backend/services/ml/app/components/factory.py`)
- ML component factory → Document classifier: creates classifier (evidence: `backend/services/ml/app/components/factory.py`)
- ML analysis API → LLM provider: uses completion backend (evidence: `README.md`)
- Input/output safeguards → LLM provider: optional analysis
