# yourdrug/rag-assistant architecture

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

## Overview

This repository is a self-hostable corporate RAG assistant with a React client and FastAPI backend. The main user workflow is document ingestion followed by a question-and-answer flow: the README documents retrieval from Qdrant, reranking, and streaming an LLM answer. Admin and user pages expose ingestion, chat, search, document, and operational capabilities. The graph includes the sampled ingestion orchestration and RAG implementation; unsampled connections are omitted rather than inferred from directory structure.

Main entry points: [`server/app/infrastructure/ml/rag_service.py`](https://github.com/yourdrug/rag-assistant/blob/main/server/app/infrastructure/ml/rag_service.py) (RAG service), [`server/app/main.py`](https://github.com/yourdrug/rag-assistant/blob/main/server/app/main.py) (FastAPI application), [`client/src/App.tsx`](https://github.com/yourdrug/rag-assistant/blob/main/client/src/App.tsx) (React application), [`server/app/presentation/api/routes/ingest.py`](https://github.com/yourdrug/rag-assistant/blob/main/server/app/presentation/api/routes/ingest.py) (Ingestion endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["React application<br/>[App.tsx]"]
  node_chat["Chat and search<br/>[chat.tsx]"]
  node_admin["Admin console<br/>[ingest.tsx]"]
end

subgraph group_api["API surface"]
  node_api["FastAPI application<br/>[main.py]"]
  node_ingest_route["Ingestion endpoints<br/>[ingest.py]"]
end

subgraph group_application["Application services"]
  node_ingest_service["Ingestion service<br/>[ingest_service.py]"]
  node_job_service["Job service<br/>[job_service.py]"]
  node_document_query["Document queries"]
  node_chunk_query["Chunk queries"]
  node_ingestion_port["Ingestion port<br/>[ingestion_port.py]"]
end

subgraph group_rag["RAG and ingestion"]
  node_rag_service["RAG service<br/>[rag_service.py]"]
  node_rag_pipeline["RAG pipeline state<br/>[rag_pipeline.py]"]
  node_document_formats["Document parsers"]
end

subgraph group_infrastructure["Infrastructure"]
  node_ingestion_registry["Ingestion registry"]
  node_postgres[("PostgreSQL<br/>[models.py]")]
  node_qdrant[("Qdrant")]
  node_reranker["Reranker"]
  node_llm["LLM"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -.->|"offers chat"| node_chat
node_web -.->|"offers administration"| node_admin
node_user -->|"asks questions"| node_api
node_user -->|"submits documents"| node_admin
node_api -->|"routes requests"| node_ingest_route
node_ingest_route -->|"calls"| node_ingest_service
node_ingest_route -->|"creates jobs"| node_job_service
node_ingest_service -->|"delegates ingestion"| node_ingestion_port
node_ingestion_port -.->|"parses documents"| node_document_formats
node_ingestion_registry -->|"reads and writes"| node_postgres
node_chat -.->|"sends questions"| node_api
node_api -.->|"dispatches chat"| node_rag_service
node_rag_service -->|"uses state"| node_rag_pipeline
node_rag_service -->|"retrieves context"| node_qdrant
node_rag_service -->|"reranks results"| node_reranker
node_rag_service -->|"streams answer"| node_llm
node_document_query -.->|"reads documents"| node_postgres
node_chunk_query -.->|"reads chunks"| node_postgres
node_ingest_service -.->|"reads registry"| node_ingestion_registry

click node_web "https://github.com/yourdrug/rag-assistant/blob/main/client/src/App.tsx"
click node_chat "https://github.com/yourdrug/rag-assistant/blob/main/client/src/pages/chat.tsx"
click node_admin "https://github.com/yourdrug/rag-assistant/blob/main/client/src/pages/admin/ingest.tsx"
click node_api "https://github.com/yourdrug/rag-assistant/blob/main/server/app/main.py"
click node_ingest_route "https://github.com/yourdrug/rag-assistant/blob/main/server/app/presentation/api/routes/ingest.py"
click node_ingest_service "https://github.com/yourdrug/rag-assistant/blob/main/server/app/application/services/ingest_service.py"
click node_job_service "https://github.com/yourdrug/rag-assistant/blob/main/server/app/application/services/job_service.py"
click node_document_query "https://github.com/yourdrug/rag-assistant/blob/main/server/app/application/services/document_query_service.py"
click node_chunk_query "https://github.com/yourdrug/rag-assistant/blob/main/server/app/application/services/chunk_query_service.py"
click node_rag_service "https://github.com/yourdrug/rag-assistant/blob/main/server/app/infrastructure/ml/rag_service.py"
click node_rag_pipeline "https://github.com/yourdrug/rag-assistant/blob/main/server/app/infrastructure/ml/rag_pipeline.py"
click node_ingestion_port "https://github.com/yourdrug/rag-assistant/blob/main/server/app/application/ports/ingestion_port.py"
click node_ingestion_registry "https://github.com/yourdrug/rag-assistant/blob/main/server/app/infrastructure/repositories/document/sqlalchemy_ingestion_registry_repository.py"
click node_postgres "https://github.com/yourdrug/rag-assistant/blob/main/server/app/infrastructure/database/models.py"
click node_document_formats "https://github.com/yourdrug/rag-assistant/tree/main/server/app/infrastructure/ml/ingestion"

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_web,node_chat,node_admin,node_user toneBlue
class node_api,node_ingest_route toneAmber
class node_ingest_service,node_job_service,node_document_query,node_chunk_query,node_ingestion_port toneMint
class node_rag_service,node_rag_pipeline,node_document_formats toneRose
class node_ingestion_registry,node_postgres,node_qdrant,node_reranker,node_llm toneIndigo
```

## Components

### Web client

- [React application](https://github.com/yourdrug/rag-assistant/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Chat and search](https://github.com/yourdrug/rag-assistant/blob/main/client/src/pages/chat.tsx): `client/src/pages/chat.tsx`
- [Admin console](https://github.com/yourdrug/rag-assistant/blob/main/client/src/pages/admin/ingest.tsx): `client/src/pages/admin/ingest.tsx`

### API surface

- [FastAPI application](https://github.com/yourdrug/rag-assistant/blob/main/server/app/main.py): `server/app/main.py`
- [Ingestion endpoints](https://github.com/yourdrug/rag-assistant/blob/main/server/app/presentation/api/routes/ingest.py): `server/app/presentation/api/routes/ingest.py`

### Application services

- [Ingestion service](https://github.com/yourdrug/rag-assistant/blob/main/server/app/application/services/ingest_service.py): `server/app/application/services/ingest_service.py`
- [Job service](https://github.com/yourdrug/rag-assistant/blob/main/server/app/application/services/job_service.py): `server/app/application/services/job_service.py`
- [Document queries](https://github.com/yourdrug/rag-assistant/blob/main/server/app/application/services/document_query_service.py): `server/app/application/services/document_query_service.py`
- [Chunk queries](https://github.com/yourdrug/rag-assistant/blob/main/server/app/application/services/chunk_query_service.py): `server/app/application/services/chunk_query_service.py`
- [Ingestion port](https://github.com/yourdrug/rag-assistant/blob/main/server/app/application/ports/ingestion_port.py): `server/app/application/ports/ingestion_port.py`

### RAG and ingestion

- [RAG service](https://github.com/yourdrug/rag-assistant/blob/main/server/app/infrastructure/ml/rag_service.py): `server/app/infrastructure/ml/rag_service.py`
- [RAG pipeline state](https://github.com/yourdrug/rag-assistant/blob/main/server/app/infrastructure/ml/rag_pipeline.py): `server/app/infrastructure/ml/rag_pipeline.py`
- [Document parsers](https://github.com/yourdrug/rag-assistant/tree/main/server/app/infrastructure/ml/ingestion): `server/app/infrastructure/ml/ingestion`

### Infrastructure

- [Ingestion registry](https://github.com/yourdrug/rag-assistant/blob/main/server/app/infrastructure/repositories/document/sqlalchemy_ingestion_registry_repository.py): `server/app/infrastructure/repositories/document/sqlalchemy_ingestion_registry_repository.py`
- [PostgreSQL](https://github.com/yourdrug/rag-assistant/blob/main/server/app/infrastructure/database/models.py): `server/app/infrastructure/database/models.py`
- **Qdrant**
- **Reranker**
- **LLM**

### Other components

- **User**

## Connections

- User → React application: uses (evidence: `README.md`)
- React application → Chat and search: offers chat
- React application → Admin console: offers administration
- User → FastAPI application: asks questions (evidence: `README.md`)
- User → Admin console: submits documents (evidence: `README.md`)
- FastAPI application → Ingestion endpoints: routes requests (evidence: `server/app/main.py`)
- Ingestion endpoints → Ingestion service: calls (evidence: `server/app/presentation/api/routes/ingest.py`)
- Ingestion endpoints → Job service: creates jobs (evidence: `server/app/presentation/api/routes/ingest.py`)
- Ingestion service → Ingestion port: delegates ingestion (evidence: `server/app/application/services/ingest_service.py`)
- Ingestion port → Document parsers: parses documents
- Ingestion registry → PostgreSQL: reads and writes (evidence: `server/app/infrastructure/repositories/document/sqlalchemy_ingestion_registry_repository.py`)
- Chat and search → FastAPI application: sends questions
- FastAPI application → RAG service: dispatches chat
- RAG service → RAG pipeline state: uses state (evidence: `server/app/infrastructure/ml/rag_service.py`)
- RAG service → Qdrant: retrieves context (evidence: `README.md`)
- RAG service → Reranker: reranks results (evidence: `README.md`)
- RAG service → LLM: streams answer (evidence: `README.md`)
- Document queries → PostgreSQL: reads documents
- Chunk queries → PostgreSQL: reads chunks
- Ingestion service → Ingestion registry: reads registry
