# tholkappiyan007/researchagent architecture

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

- Interactive diagram: https://gitdiagram.com/tholkappiyan007/researchagent
- Repository: https://github.com/tholkappiyan007/researchagent

## Overview

Research Agent is a multi-tenant RAG knowledge base with a web research interface. Users register or log in, then chat with the assistant and manage conversations and documents; document ingestion parses, cleans, chunks, embeds, and stores content for retrieval. The backend also exposes model selection and an LLM tool interface. The graph reflects README capabilities and the supplied source index; some route and frontend implementation details were not excerpted, so those relationships are left out or marked unverified.

Main entry points: [`research_agent/pipeline/ingestion.py`](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/pipeline/ingestion.py) (Ingestion pipeline), [`research_agent/api/main.py`](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/api/main.py) (FastAPI application), [`frontend/src/pages/Dashboard.jsx`](https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/pages/Dashboard.jsx) (Research dashboard), [`research_agent/api/routes/chat.py`](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/api/routes/chat.py) (Chat routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Research interface"]
  node_webapp["Web application<br/>[App.jsx]"]
  node_login["Login and registration<br/>[Login.jsx]"]
  node_dashboard["Research dashboard<br/>[Dashboard.jsx]"]
  node_chatui["Chat interface<br/>[ChatInterface.jsx]"]
  node_chatinput["Chat input<br/>[ChatInput.jsx]"]
  node_conversations["Conversation sidebar"]
  node_webapi["HTTP client<br/>[client.js]"]
  node_chatapi["Chat API client<br/>[chat.js]"]
end

subgraph group_api["API and identity"]
  node_server["FastAPI application<br/>[main.py]"]
  node_authroutes["Authentication routes<br/>[auth.py]"]
  node_chatroute["Chat routes<br/>[chat.py]"]
  node_documentsroute["Document routes<br/>[documents.py]"]
  node_modelsroute["Model routes<br/>[models.py]"]
  node_auth["Identity and tokens<br/>[security.py]"]
end

subgraph group_agent["Assistant and retrieval"]
  node_assistant["Chatbot<br/>[chatbot.py]"]
  node_memory["Conversation memory<br/>[memory.py]"]
  node_guardrails["Safety guardrails<br/>[guardrails.py]"]
  node_retriever["Retriever engine<br/>[engine.py]"]
  node_tool["Retriever tool interface<br/>[tool_interface.py]"]
  node_modelregistry["Model registry<br/>[model_registry.py]"]
end

subgraph group_knowledge["Knowledge processing and storage"]
  node_db[("Relational data<br/>[models.py]")]
  node_ingestion["Ingestion pipeline<br/>[ingestion.py]"]
  node_loaders["Document loaders"]
  node_cleaner["Text cleaner<br/>[cleaner.py]"]
  node_chunker["Token-aware chunker<br/>[chunker.py]"]
  node_embeddings["Embedding providers"]
  node_vector[("pgvector store<br/>[pgvector_store.py]")]
  node_tenants["Tenant manager<br/>[tenant_manager.py]"]
end

node_user(("User"))
node_llm{{"LLM providers"}}

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_login
node_webapp -->|"routes to"| node_dashboard
node_login -->|"calls"| node_webapi
node_dashboard -->|"renders"| node_chatui
node_dashboard -->|"renders"| node_chatinput
node_dashboard -->|"renders"| node_conversations
node_dashboard -->|"uses"| node_chatapi
node_webapi -.->|"HTTP requests"| node_server
node_chatapi -.->|"HTTP requests"| node_server
node_server -->|"mounts"| node_authroutes
node_server -->|"mounts"| node_chatroute
node_server -->|"mounts"| node_documentsroute
node_server -->|"mounts"| node_modelsroute
node_authroutes -->|"reads and writes"| node_db
node_authroutes -->|"hashes and signs"| node_auth
node_chatroute -->|"invokes"| node_assistant
node_chatroute -->|"uses"| node_memory
node_chatroute -->|"uses"| node_guardrails
node_chatroute -->|"invokes"| node_ingestion
node_documentsroute -->|"invokes"| node_ingestion
node_documentsroute -->|"reads and writes"| node_db
node_modelsroute -->|"lists models"| node_modelregistry
node_assistant -->|"applies"| node_guardrails
node_assistant -->|"selects model"| node_modelregistry
node_assistant -.->|"requests completion"| node_llm
node_guardrails -->|"checks retrieval"| node_retriever
node_tool -->|"calls"| node_retriever
node_ingestion -->|"loads files"| node_loaders
node_ingestion -->|"cleans text"| node_cleaner
node_ingestion -->|"chunks text"| node_chunker
node_ingestion -->|"embeds chunks"| node_embeddings
node_ingestion -->|"stores chunks"| node_vector
node_ingestion -->|"checks tenant"| node_tenants
node_retriever -->|"embeds query"| node_embeddings
node_retriever -->|"searches vectors"| node_vector
node_vector -->|"persists vectors"| node_db
node_tenants -->|"manages tenants"| node_db

click node_webapp "https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/App.jsx"
click node_login "https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/pages/Login.jsx"
click node_dashboard "https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/pages/Dashboard.jsx"
click node_chatui "https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/components/ChatInterface.jsx"
click node_chatinput "https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/components/ChatInput.jsx"
click node_conversations "https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/components/ConversationSidebar.jsx"
click node_webapi "https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/api/client.js"
click node_chatapi "https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/api/chat.js"
click node_server "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/api/main.py"
click node_authroutes "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/api/routes/auth.py"
click node_chatroute "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/api/routes/chat.py"
click node_documentsroute "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/api/routes/documents.py"
click node_modelsroute "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/api/routes/models.py"
click node_auth "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/auth/security.py"
click node_db "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/db/models.py"
click node_assistant "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/agent/chatbot.py"
click node_memory "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/agent/memory.py"
click node_guardrails "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/agent/guardrails.py"
click node_retriever "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/retriever/engine.py"
click node_tool "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/retriever/tool_interface.py"
click node_ingestion "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/pipeline/ingestion.py"
click node_loaders "https://github.com/tholkappiyan007/researchagent/tree/master/research_agent/document_loaders"
click node_cleaner "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/processors/cleaner.py"
click node_chunker "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/processors/chunker.py"
click node_embeddings "https://github.com/tholkappiyan007/researchagent/tree/master/research_agent/embeddings"
click node_vector "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/vector_store/pgvector_store.py"
click node_tenants "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/vector_store/tenant_manager.py"
click node_modelregistry "https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/config/model_registry.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_webapp,node_login,node_dashboard,node_chatui,node_chatinput,node_conversations,node_webapi,node_chatapi,node_user toneBlue
class node_server,node_authroutes,node_chatroute,node_documentsroute,node_modelsroute,node_auth toneAmber
class node_assistant,node_memory,node_guardrails,node_retriever,node_tool,node_modelregistry toneMint
class node_db,node_ingestion,node_loaders,node_cleaner,node_chunker,node_embeddings,node_vector,node_tenants toneRose
class node_llm toneIndigo
```

## Components

### Research interface

- [Web application](https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Login and registration](https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [Research dashboard](https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Chat interface](https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/components/ChatInterface.jsx): `frontend/src/components/ChatInterface.jsx`
- [Chat input](https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/components/ChatInput.jsx): `frontend/src/components/ChatInput.jsx`
- [Conversation sidebar](https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/components/ConversationSidebar.jsx): `frontend/src/components/ConversationSidebar.jsx`
- [HTTP client](https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Chat API client](https://github.com/tholkappiyan007/researchagent/blob/master/frontend/src/api/chat.js): `frontend/src/api/chat.js`

### API and identity

- [FastAPI application](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/api/main.py): `research_agent/api/main.py`
- [Authentication routes](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/api/routes/auth.py): `research_agent/api/routes/auth.py`
- [Chat routes](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/api/routes/chat.py): `research_agent/api/routes/chat.py`
- [Document routes](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/api/routes/documents.py): `research_agent/api/routes/documents.py`
- [Model routes](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/api/routes/models.py): `research_agent/api/routes/models.py`
- [Identity and tokens](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/auth/security.py): `research_agent/auth/security.py`

### Assistant and retrieval

- [Chatbot](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/agent/chatbot.py): `research_agent/agent/chatbot.py`
- [Conversation memory](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/agent/memory.py): `research_agent/agent/memory.py`
- [Safety guardrails](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/agent/guardrails.py): `research_agent/agent/guardrails.py`
- [Retriever engine](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/retriever/engine.py): `research_agent/retriever/engine.py`
- [Retriever tool interface](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/retriever/tool_interface.py): `research_agent/retriever/tool_interface.py`
- [Model registry](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/config/model_registry.py): `research_agent/config/model_registry.py`

### Knowledge processing and storage

- [Relational data](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/db/models.py): `research_agent/db/models.py`
- [Ingestion pipeline](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/pipeline/ingestion.py): `research_agent/pipeline/ingestion.py`
- [Document loaders](https://github.com/tholkappiyan007/researchagent/tree/master/research_agent/document_loaders): `research_agent/document_loaders`
- [Text cleaner](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/processors/cleaner.py): `research_agent/processors/cleaner.py`
- [Token-aware chunker](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/processors/chunker.py): `research_agent/processors/chunker.py`
- [Embedding providers](https://github.com/tholkappiyan007/researchagent/tree/master/research_agent/embeddings): `research_agent/embeddings`
- [pgvector store](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/vector_store/pgvector_store.py): `research_agent/vector_store/pgvector_store.py`
- [Tenant manager](https://github.com/tholkappiyan007/researchagent/blob/master/research_agent/vector_store/tenant_manager.py): `research_agent/vector_store/tenant_manager.py`

### Other components

- **User**
- **LLM providers**

## Connections

- User → Web application: uses (evidence: `frontend/src/App.jsx`)
- Web application → Login and registration: routes to (evidence: `frontend/src/App.jsx`)
- Web application → Research dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Login and registration → HTTP client: calls (evidence: `frontend/src/pages/Login.jsx`)
- Research dashboard → Chat interface: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Research dashboard → Chat input: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Research dashboard → Conversation sidebar: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Research dashboard → Chat API client: uses (evidence: `frontend/src/pages/Dashboard.jsx`)
- HTTP client → FastAPI application: HTTP requests
- Chat API client → FastAPI application: HTTP requests
- FastAPI application → Authentication routes: mounts (evidence: `research_agent/api/main.py`)
- FastAPI application → Chat routes: mounts (evidence: `research_agent/api/main.py`)
- FastAPI application → Document routes: mounts (evidence: `research_agent/api/main.py`)
- FastAPI application → Model routes: mounts (evidence: `research_agent/api/main.py`)
- Authentication routes → Relational data: reads and writes (evidence: `research_agent/api/routes/auth.py`)
- Authentication routes → Identity and tokens: hashes and signs (evidence: `research_agent/api/routes/auth.py`)
- Chat routes → Chatbot: invokes (evidence: `research_agent/api/routes/chat.py`)
- Chat routes → Conversation memory: uses (evidence: `research_agent/api/routes/chat.py`)
- Chat routes → Safety guardrails: uses (evidence: `research_agent/api/routes/chat.py`)
- Chat routes → Ingestion pipeline: invokes (evidence: `research_agent/api/routes/chat.py`)
- Document routes → Ingestion pipeline: invokes (evidence: `research_agent/api/routes/documents.py`)
- Document routes → Relational data: reads and writes (evidence: `research_agent/api/routes/documents.py`)
- Model routes → Model registry: lists models (evidence: `research_agent/api/routes/models.py`)
- Chatbot → Safety guardrails: applies (evidence: `research_agent/agent/chatbot.py`)
- Chatbot → Model registry: selects model (evidence: `research_agent/agent/chatbot.py`)
- Chatbot → LLM providers: requests completion
- Safety guardrails → Retriever engine: checks retrieval (evidence: `research_agent/agent/guardrails.py`)
- Retriever tool interface → Retriever engine: calls (evidence: `research_agent/retriever/tool_interface.py`)
- Ingestion pipeline → Document loaders: loads files (evidence: `research_agent/pipeline/ingestion.py`)
- Ingestion pipeline → Text cleaner: cleans text (evidence: `research_agent/pipeline/ingestion.py`)
- Ingestion pipeline → Token-aware chunker: chunks text (evidence: `research_agent/pipeline/ingestion.py`)
- Ingestion pipeline → Embedding providers: embeds chunks (evidence: `research_agent/pipeline/ingestion.py`)
- Ingestion pipeline → pgvector store: stores chunks (evidence: `research_agent/pipeline/ingestion.py`)
- Ingestion pipeline → Tenant manager: checks tenant (evidence: `research_agent/pipeline/ingestion.py`)
- Retriever engine → Embedding providers: embeds query (evidence: `research_agent/retriever/engine.py`)
- Retriever engine → pgvector store: searches vectors (evidence: `research_agent/retriever/engine.py`)
- pgvector store → Relational data: persists vectors (evidence: `research_agent/vector_store/pgvector_store.py`)
- Tenant manager → Relational data: manages tenants (evidence: `research_agent/vector_store/tenant_manager.py`)
