# sukumarmuthusamy/docmind-xai architecture

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

- Interactive diagram: https://gitdiagram.com/sukumarmuthusamy/docmind-xai
- Repository: https://github.com/sukumarmuthusamy/docmind-xai

## Overview

DocMind XAI is a local-first document RAG application. Users upload documents for asynchronous parsing, chunking, embedding, and storage, then search or chat over them; chat streams answers with citations and an auditable XAI trail. The map includes the documented health/model endpoints and intent routing. Source excerpts show the ingestion and retrieval internals; chat generation and several route implementations are not excerpted, so those internal links are omitted where unverified.

Main entry points: [`backend/app/api/router.py`](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/router.py) (API router), [`backend/app/services/retrieval.py`](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/retrieval.py) (Hybrid retrieval and XAI), [`backend/app/services/pipeline.py`](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/pipeline.py) (Ingestion orchestration), [`backend/app/api/routes/chat.py`](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/routes/chat.py) (Chat endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_frontend["Web app shell<br/>[AppShell.tsx]"]
  node_chatui["Streaming chat UI<br/>[Chat.tsx]"]
  node_uploadui["Document upload UI<br/>[DocumentUpload.tsx]"]
  node_proxy["Frontend API proxy<br/>[_backend.ts]"]
end

subgraph group_api["API and routing"]
  node_apiapp["FastAPI application<br/>[main.py]"]
  node_router["API router<br/>[router.py]"]
  node_ingestapi["Upload and task status<br/>[ingest.py]"]
  node_chatapi["Chat endpoint<br/>[chat.py]"]
  node_searchapi["Search endpoint<br/>[search.py]"]
  node_documentsapi["Document listing<br/>[documents.py]"]
  node_healthapi["Health and model routes<br/>[health.py]"]
end

subgraph group_ingestion["Document ingestion"]
  node_worker["Celery worker<br/>[worker.py]"]
  node_task["Ingestion task<br/>[ingestion.py]"]
  node_pipeline["Ingestion orchestration<br/>[pipeline.py]"]
  node_parser["Parse and chunk<br/>[ingestion.py]"]
  node_embeddings["Embedding generation<br/>[embeddings.py]"]
end

subgraph group_rag["Search and answers"]
  node_intent["Intent routing<br/>[intent_router.py]"]
  node_retrieval["Hybrid retrieval and XAI<br/>[retrieval.py]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
  node_llm["Answer generation<br/>[llm.py]"]
end

subgraph group_state["Persistence and services"]
  node_vector[("FAISS vector index<br/>[vector_store.py]")]
  node_db[("PostgreSQL records<br/>[session.py]")]
  node_ollama["Ollama service<br/>[ollama_client.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

node_user(("User"))
node_redis["Redis broker and results"]
node_ollamasvc["Ollama runtime"]

node_user -->|"uses"| node_frontend
node_frontend -->|"renders"| node_chatui
node_frontend -->|"renders"| node_uploadui
node_chatui -->|"requests via"| node_proxy
node_uploadui -.->|"requests via"| node_proxy
node_proxy -.->|"forwards requests"| node_apiapp
node_apiapp -->|"mounts"| node_router
node_router -->|"registers"| node_ingestapi
node_router -->|"registers"| node_chatapi
node_router -->|"registers"| node_searchapi
node_router -->|"registers"| node_documentsapi
node_router -->|"registers"| node_healthapi
node_ingestapi -->|"enqueues task"| node_worker
node_worker -.->|"uses broker"| node_redis
node_redis -.->|"dispatches"| node_task
node_task -->|"invokes"| node_pipeline
node_pipeline -->|"parses and chunks"| node_parser
node_pipeline -->|"embeds chunks"| node_embeddings
node_pipeline -->|"writes vectors"| node_vector
node_pipeline -->|"persists records"| node_db
node_chatapi -->|"classifies query"| node_intent
node_chatapi -->|"requests evidence"| node_retrieval
node_chatapi -->|"requests answer"| node_llm
node_searchapi -->|"classifies query"| node_intent
node_searchapi -->|"requests results"| node_retrieval
node_retrieval -->|"reads chunks"| node_db
node_retrieval -->|"searches vectors"| node_vector
node_retrieval -->|"embeds query"| node_embeddings
node_retrieval -->|"reranks candidates"| node_reranker
node_llm -.->|"generates with"| node_ollama
node_ollama -.->|"calls"| node_ollamasvc
node_documentsapi -->|"reads documents"| node_db
node_ingestapi -.->|"polls task status"| node_redis
node_healthapi -.->|"checks service"| node_ollama
node_chatui -->|"shows citations"| node_user

click node_frontend "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/frontend/components/AppShell.tsx"
click node_chatui "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/frontend/components/Chat.tsx"
click node_uploadui "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/frontend/components/DocumentUpload.tsx"
click node_proxy "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/frontend/app/api/_backend.ts"
click node_apiapp "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/main.py"
click node_router "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/router.py"
click node_ingestapi "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/routes/ingest.py"
click node_chatapi "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/routes/chat.py"
click node_searchapi "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/routes/search.py"
click node_documentsapi "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/routes/documents.py"
click node_healthapi "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/routes/health.py"
click node_worker "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/worker.py"
click node_task "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/tasks/ingestion.py"
click node_pipeline "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/pipeline.py"
click node_parser "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/ingestion.py"
click node_embeddings "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/embeddings.py"
click node_vector "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/vector_store.py"
click node_db "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/db/session.py"
click node_intent "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/intent_router.py"
click node_retrieval "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/retrieval.py"
click node_reranker "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/reranker.py"
click node_llm "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/llm.py"
click node_ollama "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/ollama_client.py"
click node_config "https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/core/config.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_chatui,node_uploadui,node_proxy,node_user toneBlue
class node_apiapp,node_router,node_ingestapi,node_chatapi,node_searchapi,node_documentsapi,node_healthapi,node_redis toneAmber
class node_worker,node_task,node_pipeline,node_parser,node_embeddings toneMint
class node_intent,node_retrieval,node_reranker,node_llm toneRose
class node_vector,node_db,node_ollama,node_config,node_ollamasvc toneIndigo
```

## Components

### User interface

- [Web app shell](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/frontend/components/AppShell.tsx): `frontend/components/AppShell.tsx`
- [Streaming chat UI](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/frontend/components/Chat.tsx): `frontend/components/Chat.tsx`
- [Document upload UI](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/frontend/components/DocumentUpload.tsx): `frontend/components/DocumentUpload.tsx`
- [Frontend API proxy](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/frontend/app/api/_backend.ts): `frontend/app/api/_backend.ts`

### API and routing

- [FastAPI application](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Upload and task status](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/routes/ingest.py): `backend/app/api/routes/ingest.py`
- [Chat endpoint](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/routes/chat.py): `backend/app/api/routes/chat.py`
- [Search endpoint](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/routes/search.py): `backend/app/api/routes/search.py`
- [Document listing](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/routes/documents.py): `backend/app/api/routes/documents.py`
- [Health and model routes](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/api/routes/health.py): `backend/app/api/routes/health.py`

### Document ingestion

- [Celery worker](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/worker.py): `backend/app/worker.py`
- [Ingestion task](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/tasks/ingestion.py): `backend/app/tasks/ingestion.py`
- [Ingestion orchestration](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/pipeline.py): `backend/app/services/pipeline.py`
- [Parse and chunk](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/ingestion.py): `backend/app/services/ingestion.py`
- [Embedding generation](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/embeddings.py): `backend/app/services/embeddings.py`

### Search and answers

- [Intent routing](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/intent_router.py): `backend/app/services/intent_router.py`
- [Hybrid retrieval and XAI](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/retrieval.py): `backend/app/services/retrieval.py`
- [Cross-encoder reranker](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/reranker.py): `backend/app/services/reranker.py`
- [Answer generation](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/llm.py): `backend/app/services/llm.py`

### Persistence and services

- [FAISS vector index](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/vector_store.py): `backend/app/services/vector_store.py`
- [PostgreSQL records](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Ollama service](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/services/ollama_client.py): `backend/app/services/ollama_client.py`
- [Runtime settings](https://github.com/sukumarmuthusamy/docmind-xai/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### Other components

- **User**
- **Redis broker and results**
- **Ollama runtime**

## Connections

- User → Web app shell: uses
- Web app shell → Streaming chat UI: renders (evidence: `frontend/components/AppShell.tsx`)
- Web app shell → Document upload UI: renders (evidence: `frontend/components/AppShell.tsx`)
- Streaming chat UI → Frontend API proxy: requests via (evidence: `frontend/components/Chat.tsx`)
- Document upload UI → Frontend API proxy: requests via
- Frontend API proxy → FastAPI application: forwards requests
- FastAPI application → API router: mounts (evidence: `backend/app/main.py`)
- API router → Upload and task status: registers (evidence: `backend/app/api/router.py`)
- API router → Chat endpoint: registers (evidence: `backend/app/api/router.py`)
- API router → Search endpoint: registers (evidence: `backend/app/api/router.py`)
- API router → Document listing: registers (evidence: `backend/app/api/router.py`)
- API router → Health and model routes: registers (evidence: `backend/app/api/router.py`)
- Upload and task status → Celery worker: enqueues task (evidence: `backend/app/api/routes/ingest.py`)
- Celery worker → Redis broker and results: uses broker
- Redis broker and results → Ingestion task: dispatches
- Ingestion task → Ingestion orchestration: invokes (evidence: `backend/app/tasks/ingestion.py`)
- Ingestion orchestration → Parse and chunk: parses and chunks (evidence: `backend/app/services/pipeline.py`)
- Ingestion orchestration → Embedding generation: embeds chunks (evidence: `backend/app/services/pipeline.py`)
- Ingestion orchestration → FAISS vector index: writes vectors (evidence: `backend/app/services/pipeline.py`)
- Ingestion orchestration → PostgreSQL records: persists records (evidence: `backend/app/services/pipeline.py`)
- Chat endpoint → Intent routing: classifies query (evidence: `backend/app/api/routes/chat.py`)
- Chat endpoint → Hybrid retrieval and XAI: requests evidence (evidence: `backend/app/api/routes/chat.py`)
- Chat endpoint → Answer generation: requests answer (evidence: `backend/app/api/routes/chat.py`)
- Search endpoint → Intent routing: classifies query (evidence: `backend/app/api/routes/search.py`)
- Search endpoint → Hybrid retrieval and XAI: requests results (evidence: `backend/app/api/routes/search.py`)
- Hybrid retrieval and XAI → PostgreSQL records: reads chunks (evidence: `backend/app/services/retrieval.py`)
- Hybrid retrieval and XAI → FAISS vector index: searches vectors (evidence: `backend/app/services/retrieval.py`)
- Hybrid retrieval and XAI → Embedding generation: embeds query (evidence: `backend/app/services/retrieval.py`)
- Hybrid retrieval and XAI → Cross-encoder reranker: reranks candidates (evidence: `backend/app/services/retrieval.py`)
- Answer generation → Ollama service: generates with
- Ollama service → Ollama runtime: calls
- Document listing → PostgreSQL records: reads documents (evidence: `backend/app/api/routes/documents.py`)
- Upload and task status → Redis broker and results: polls task status
- Health and model routes → Ollama service: checks service
- Streaming chat UI → User: shows citations (evidence: `frontend/components/Chat.tsx`)
