# robayedl/documind architecture

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

- Interactive diagram: https://gitdiagram.com/robayedl/documind
- Repository: https://github.com/robayedl/documind

## Overview

DocuMind is a multi-tenant document intelligence product: users upload PDFs or DOCX files, which are parsed and indexed asynchronously, then ask questions answered with hybrid retrieval and a revisable multi-agent RAG workflow. The graph also preserves documented MCP access, usage tracking, caching, and privacy/auth capabilities. Some relationships come from README architecture statements and the source index; unsampled implementations are represented at their known source paths, without inferring their internal call details.

Main entry points: [`app/main.py`](https://github.com/robayedl/documind/blob/main/app/main.py) (FastAPI service), [`rag/agents/researcher.py`](https://github.com/robayedl/documind/blob/main/rag/agents/researcher.py) (Research and tool use), [`rag/chains/retrieval.py`](https://github.com/robayedl/documind/blob/main/rag/chains/retrieval.py) (Hybrid retrieval and HyDE), [`worker/tasks.py`](https://github.com/robayedl/documind/blob/main/worker/tasks.py) (Ingestion task)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webchat["Chat interface<br/>[ChatClient.tsx]"]
  node_webapi["API client<br/>[api.ts]"]
end

subgraph group_api["API and tenancy"]
  node_apiapp["FastAPI service<br/>[main.py]"]
  node_auth["Clerk authentication<br/>[auth.py]"]
  node_redaction["PII redaction<br/>[redact.py]"]
  node_cache[("Semantic cache<br/>[cache.py]")]
  node_postgres[("PostgreSQL and pgvector<br/>[db.py]")]
end

subgraph group_ingestion["Document ingestion"]
  node_worker["Ingestion task<br/>[tasks.py]"]
  node_queue["Celery queue<br/>[celery_app.py]"]
  node_ingest["Document parsing and indexing<br/>[ingest.py]"]
  node_contextualize["Chunk contextualization<br/>[contextualize.py]"]
  node_storage["Uploaded-file storage<br/>[storage.py]"]
end

subgraph group_query["RAG answering"]
  node_graph["Agent supervisor graph<br/>[graph.py]"]
  node_researcher["Research and tool use<br/>[researcher.py]"]
  node_retrieval["Hybrid retrieval and HyDE<br/>[retrieval.py]"]
  node_rerank["Cross-encoder reranking<br/>[rerank.py]"]
  node_store[("Chunk and vector store<br/>[store.py]")]
  node_synth["Answer synthesis<br/>[synthesizer.py]"]
  node_critic["Answer critique<br/>[critic.py]"]
  node_tools["Search and calculator tools"]
  node_llm["Gemini and embeddings<br/>[llm.py]"]
end

subgraph group_access["Integrations and usage"]
  node_mcp["MCP document tools<br/>[server.py]"]
  node_mcpauth["API-key validation<br/>[auth.py]"]
  node_usage["Token and cost usage<br/>[usage.py]"]
end

node_user(("User"))
node_external{{"LLM and search providers"}}

node_user -->|"asks questions"| node_webchat
node_webchat -->|"sends requests"| node_webapi
node_webapi -->|"calls API"| node_apiapp
node_apiapp -->|"validates users"| node_auth
node_apiapp -->|"redacts queries"| node_redaction
node_apiapp -->|"checks responses"| node_cache
node_apiapp -->|"runs agent graph"| node_graph
node_graph -->|"dispatches research"| node_researcher
node_researcher -->|"retrieves passages"| node_retrieval
node_retrieval -->|"searches chunks"| node_store
node_retrieval -->|"reranks candidates"| node_rerank
node_researcher -->|"calls selected tools"| node_tools
node_researcher -->|"provides research"| node_synth
node_synth -->|"submits draft"| node_critic
node_critic -->|"requests revision"| node_synth
node_apiapp -->|"queues ingestion"| node_worker
node_worker -->|"runs as task"| node_queue
node_worker -->|"indexes documents"| node_ingest
node_ingest -->|"contextualizes chunks"| node_contextualize
node_ingest -->|"writes indexed chunks"| node_store
node_apiapp -->|"saves uploads"| node_storage
node_apiapp -->|"persists metadata"| node_postgres
node_store -->|"reads and writes vectors"| node_postgres
node_mcp -->|"validates API keys"| node_mcpauth
node_mcp -->|"searches documents"| node_retrieval
node_graph -->|"tracks usage"| node_usage
node_llm -->|"invokes Gemini"| node_external
node_tools -.->|"uses web search"| node_external

click node_webchat "https://github.com/robayedl/documind/blob/main/web/app/chat/ChatClient.tsx"
click node_webapi "https://github.com/robayedl/documind/blob/main/web/lib/api.ts"
click node_apiapp "https://github.com/robayedl/documind/blob/main/app/main.py"
click node_auth "https://github.com/robayedl/documind/blob/main/app/auth.py"
click node_redaction "https://github.com/robayedl/documind/blob/main/app/redact.py"
click node_cache "https://github.com/robayedl/documind/blob/main/rag/cache.py"
click node_postgres "https://github.com/robayedl/documind/blob/main/app/db.py"
click node_worker "https://github.com/robayedl/documind/blob/main/worker/tasks.py"
click node_queue "https://github.com/robayedl/documind/blob/main/worker/celery_app.py"
click node_ingest "https://github.com/robayedl/documind/blob/main/rag/ingest.py"
click node_contextualize "https://github.com/robayedl/documind/blob/main/rag/contextualize.py"
click node_storage "https://github.com/robayedl/documind/blob/main/app/storage.py"
click node_graph "https://github.com/robayedl/documind/blob/main/rag/agents/graph.py"
click node_researcher "https://github.com/robayedl/documind/blob/main/rag/agents/researcher.py"
click node_retrieval "https://github.com/robayedl/documind/blob/main/rag/chains/retrieval.py"
click node_rerank "https://github.com/robayedl/documind/blob/main/rag/chains/rerank.py"
click node_store "https://github.com/robayedl/documind/blob/main/rag/store.py"
click node_synth "https://github.com/robayedl/documind/blob/main/rag/agents/synthesizer.py"
click node_critic "https://github.com/robayedl/documind/blob/main/rag/agents/critic.py"
click node_tools "https://github.com/robayedl/documind/tree/main/rag/tools"
click node_llm "https://github.com/robayedl/documind/blob/main/rag/llm.py"
click node_mcp "https://github.com/robayedl/documind/blob/main/mcp_server/server.py"
click node_mcpauth "https://github.com/robayedl/documind/blob/main/mcp_server/auth.py"
click node_usage "https://github.com/robayedl/documind/blob/main/rag/usage.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_webchat,node_webapi,node_user toneBlue
class node_apiapp,node_auth,node_redaction,node_cache,node_postgres toneAmber
class node_worker,node_queue,node_ingest,node_contextualize,node_storage toneMint
class node_graph,node_researcher,node_retrieval,node_rerank,node_store,node_synth,node_critic,node_tools,node_llm toneRose
class node_mcp,node_mcpauth,node_usage,node_external toneIndigo
```

## Components

### Web client

- [Chat interface](https://github.com/robayedl/documind/blob/main/web/app/chat/ChatClient.tsx): `web/app/chat/ChatClient.tsx`
- [API client](https://github.com/robayedl/documind/blob/main/web/lib/api.ts): `web/lib/api.ts`

### API and tenancy

- [FastAPI service](https://github.com/robayedl/documind/blob/main/app/main.py): `app/main.py`
- [Clerk authentication](https://github.com/robayedl/documind/blob/main/app/auth.py): `app/auth.py`
- [PII redaction](https://github.com/robayedl/documind/blob/main/app/redact.py): `app/redact.py`
- [Semantic cache](https://github.com/robayedl/documind/blob/main/rag/cache.py): `rag/cache.py`
- [PostgreSQL and pgvector](https://github.com/robayedl/documind/blob/main/app/db.py): `app/db.py`

### Document ingestion

- [Ingestion task](https://github.com/robayedl/documind/blob/main/worker/tasks.py): `worker/tasks.py`
- [Celery queue](https://github.com/robayedl/documind/blob/main/worker/celery_app.py): `worker/celery_app.py`
- [Document parsing and indexing](https://github.com/robayedl/documind/blob/main/rag/ingest.py): `rag/ingest.py`
- [Chunk contextualization](https://github.com/robayedl/documind/blob/main/rag/contextualize.py): `rag/contextualize.py`
- [Uploaded-file storage](https://github.com/robayedl/documind/blob/main/app/storage.py): `app/storage.py`

### RAG answering

- [Agent supervisor graph](https://github.com/robayedl/documind/blob/main/rag/agents/graph.py): `rag/agents/graph.py`
- [Research and tool use](https://github.com/robayedl/documind/blob/main/rag/agents/researcher.py): `rag/agents/researcher.py`
- [Hybrid retrieval and HyDE](https://github.com/robayedl/documind/blob/main/rag/chains/retrieval.py): `rag/chains/retrieval.py`
- [Cross-encoder reranking](https://github.com/robayedl/documind/blob/main/rag/chains/rerank.py): `rag/chains/rerank.py`
- [Chunk and vector store](https://github.com/robayedl/documind/blob/main/rag/store.py): `rag/store.py`
- [Answer synthesis](https://github.com/robayedl/documind/blob/main/rag/agents/synthesizer.py): `rag/agents/synthesizer.py`
- [Answer critique](https://github.com/robayedl/documind/blob/main/rag/agents/critic.py): `rag/agents/critic.py`
- [Search and calculator tools](https://github.com/robayedl/documind/tree/main/rag/tools): `rag/tools`
- [Gemini and embeddings](https://github.com/robayedl/documind/blob/main/rag/llm.py): `rag/llm.py`

### Integrations and usage

- [MCP document tools](https://github.com/robayedl/documind/blob/main/mcp_server/server.py): `mcp_server/server.py`
- [API-key validation](https://github.com/robayedl/documind/blob/main/mcp_server/auth.py): `mcp_server/auth.py`
- [Token and cost usage](https://github.com/robayedl/documind/blob/main/rag/usage.py): `rag/usage.py`

### Other components

- **User**
- **LLM and search providers**

## Connections

- User → Chat interface: asks questions
- Chat interface → API client: sends requests (evidence: `web/app/chat/ChatClient.tsx`)
- API client → FastAPI service: calls API
- FastAPI service → Clerk authentication: validates users (evidence: `app/main.py`)
- FastAPI service → PII redaction: redacts queries (evidence: `app/main.py`)
- FastAPI service → Semantic cache: checks responses (evidence: `app/main.py`)
- FastAPI service → Agent supervisor graph: runs agent graph (evidence: `app/main.py`)
- Agent supervisor graph → Research and tool use: dispatches research
- Research and tool use → Hybrid retrieval and HyDE: retrieves passages (evidence: `rag/agents/researcher.py`)
- Hybrid retrieval and HyDE → Chunk and vector store: searches chunks (evidence: `rag/chains/retrieval.py`)
- Hybrid retrieval and HyDE → Cross-encoder reranking: reranks candidates (evidence: `rag/chains/retrieval.py`)
- Research and tool use → Search and calculator tools: calls selected tools (evidence: `rag/agents/researcher.py`)
- Research and tool use → Answer synthesis: provides research
- Answer synthesis → Answer critique: submits draft
- Answer critique → Answer synthesis: requests revision
- FastAPI service → Ingestion task: queues ingestion (evidence: `app/main.py`)
- Ingestion task → Celery queue: runs as task (evidence: `worker/tasks.py`)
- Ingestion task → Document parsing and indexing: indexes documents (evidence: `worker/tasks.py`)
- Document parsing and indexing → Chunk contextualization: contextualizes chunks (evidence: `rag/ingest.py`)
- Document parsing and indexing → Chunk and vector store: writes indexed chunks (evidence: `rag/ingest.py`)
- FastAPI service → Uploaded-file storage: saves uploads (evidence: `app/main.py`)
- FastAPI service → PostgreSQL and pgvector: persists metadata (evidence: `app/main.py`)
- Chunk and vector store → PostgreSQL and pgvector: reads and writes vectors (evidence: `rag/store.py`)
- MCP document tools → API-key validation: validates API keys (evidence: `mcp_server/server.py`)
- MCP document tools → Hybrid retrieval and HyDE: searches documents (evidence: `mcp_server/server.py`)
- Agent supervisor graph → Token and cost usage: tracks usage (evidence: `rag/agents/graph.py`)
- Gemini and embeddings → LLM and search providers: invokes Gemini (evidence: `rag/llm.py`)
- Search and calculator tools → LLM and search providers: uses web search