# yogendrachukka01/adaptiveagent architecture

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

- Interactive diagram: https://gitdiagram.com/yogendrachukka01/adaptiveagent
- Repository: https://github.com/yogendrachukka01/adaptiveagent

## Overview

AdaptiveAgent is a private-knowledge-base Agentic RAG platform. A user submits a chat query or uploads a document; chat requests enter the LangGraph workflow, retrieve evidence, generate and evaluate an answer, then stream results and review metadata to the frontend. The graph preserves major documented stages and supporting API, retrieval, LLM, and memory capabilities. Most individual node and service implementations were not sampled, so their internal calls are shown only where the README or source index supports them.

Main entry points: [`backend/app/graph/builder.py`](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/graph/builder.py) (Graph builder), [`backend/app/api/chat.py`](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/api/chat.py) (Chat API), [`frontend/src/lib/api.ts`](https://github.com/yogendrachukka01/adaptiveagent/blob/main/frontend/src/lib/api.ts) (API client), [`frontend/src/app/page.tsx`](https://github.com/yogendrachukka01/adaptiveagent/blob/main/frontend/src/app/page.tsx) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_ui["Chat interface<br/>[page.tsx]"]
  node_chat_view["Message display<br/>[MessageBubble.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and state"]
  node_chat_api["Chat API<br/>[chat.py]"]
  node_upload_api["Upload API<br/>[upload.py]"]
  node_auth["API key auth<br/>[auth.py]"]
  node_config["Runtime config<br/>[config.py]"]
  node_dependencies["API dependencies<br/>[deps.py]"]
  node_threads["Thread state<br/>[threads.py]"]
  node_agent_state["Agent state<br/>[state.py]"]
end

subgraph group_pipeline["Agent workflow"]
  node_graph_builder["Graph builder<br/>[builder.py]"]
  node_routing["Conditional routing<br/>[conditional.py]"]
  node_workflow_nodes["Workflow stages"]
  node_retrieval_node["Retrieval stage<br/>[retrieval_node.py]"]
  node_response_node["Response stage<br/>[response_node.py]"]
  node_eval_node["Evaluation stage<br/>[eval_node.py]"]
  node_refine_node["Refine stage<br/>[refine_node.py]"]
end

subgraph group_services["AI and retrieval"]
  node_validator_service["Query validation<br/>[validator.py]"]
  node_hybrid_search["Hybrid search<br/>[hybrid_search.py]"]
  node_llm["LLM providers<br/>[llm.py]"]
  node_memory["Conversation memory<br/>[memory.py]"]
  node_memory_worker["Memory distiller<br/>[memory_worker.py]"]
  node_vector_stores[("Vector stores")]
end

node_user(("User"))
node_result["Streamed answer"]
node_document["Knowledge document"]

node_user -->|"asks query"| node_ui
node_ui -->|"requests stream"| node_api_client
node_api_client -->|"sends SSE request"| node_chat_api
node_chat_api -->|"invokes graph"| node_graph_builder
node_graph_builder -->|"registers stages"| node_workflow_nodes
node_graph_builder -->|"configures routing"| node_routing
node_graph_builder -->|"registers retrieval"| node_retrieval_node
node_graph_builder -->|"registers response"| node_response_node
node_graph_builder -->|"registers evaluation"| node_eval_node
node_graph_builder -->|"registers refinement"| node_refine_node
node_workflow_nodes -.->|"validates query"| node_validator_service
node_retrieval_node -->|"searches evidence"| node_hybrid_search
node_retrieval_node -.->|"retrieves candidates"| node_vector_stores
node_workflow_nodes -.->|"uses providers"| node_llm
node_response_node -->|"evaluates output"| node_eval_node
node_eval_node -->|"routes low scores"| node_refine_node
node_refine_node -->|"retries retrieval"| node_retrieval_node
node_chat_api -->|"streams response"| node_result
node_result -->|"delivers SSE"| node_api_client
node_api_client -->|"yields events"| node_ui
node_ui -->|"renders messages"| node_chat_view
node_user -->|"uploads document"| node_document
node_ui -->|"uploads file"| node_api_client
node_api_client -.->|"posts file"| node_upload_api
node_chat_api -->|"checks API key"| node_auth
node_chat_api -->|"uses thread state"| node_threads
node_chat_api -->|"stores conversation"| node_memory
node_memory_worker -->|"reads conversations"| node_memory
node_memory_worker -->|"extracts facts"| node_llm
node_memory_worker -.->|"stores distilled facts"| node_vector_stores

click node_ui "https://github.com/yogendrachukka01/adaptiveagent/blob/main/frontend/src/app/page.tsx"
click node_chat_view "https://github.com/yogendrachukka01/adaptiveagent/blob/main/frontend/src/components/chat/MessageBubble.tsx"
click node_api_client "https://github.com/yogendrachukka01/adaptiveagent/blob/main/frontend/src/lib/api.ts"
click node_chat_api "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/api/chat.py"
click node_upload_api "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/api/upload.py"
click node_auth "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/core/auth.py"
click node_config "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/core/config.py"
click node_dependencies "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/core/deps.py"
click node_threads "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/core/threads.py"
click node_agent_state "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/models/state.py"
click node_graph_builder "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/graph/builder.py"
click node_routing "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/graph/edges/conditional.py"
click node_workflow_nodes "https://github.com/yogendrachukka01/adaptiveagent/tree/main/backend/app/graph/nodes"
click node_retrieval_node "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/graph/nodes/retrieval_node.py"
click node_response_node "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/graph/nodes/response_node.py"
click node_eval_node "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/graph/nodes/eval_node.py"
click node_refine_node "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/graph/nodes/refine_node.py"
click node_validator_service "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/services/validator/validator.py"
click node_hybrid_search "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/services/retrieval/hybrid_search.py"
click node_llm "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/services/llm.py"
click node_memory "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/services/memory/memory.py"
click node_memory_worker "https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/services/memory/memory_worker.py"
click node_vector_stores "https://github.com/yogendrachukka01/adaptiveagent/tree/main/backend/app/services/retrieval/vector_store"

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_ui,node_chat_view,node_api_client,node_user toneBlue
class node_chat_api,node_upload_api,node_auth,node_config,node_dependencies,node_threads,node_agent_state toneAmber
class node_graph_builder,node_routing,node_workflow_nodes,node_retrieval_node,node_response_node,node_eval_node,node_refine_node toneMint
class node_validator_service,node_hybrid_search,node_llm,node_memory,node_memory_worker,node_vector_stores toneRose
class node_result,node_document toneIndigo
```

## Components

### Web client

- [Chat interface](https://github.com/yogendrachukka01/adaptiveagent/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Message display](https://github.com/yogendrachukka01/adaptiveagent/blob/main/frontend/src/components/chat/MessageBubble.tsx): `frontend/src/components/chat/MessageBubble.tsx`
- [API client](https://github.com/yogendrachukka01/adaptiveagent/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and state

- [Chat API](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Upload API](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/api/upload.py): `backend/app/api/upload.py`
- [API key auth](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/core/auth.py): `backend/app/core/auth.py`
- [Runtime config](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [API dependencies](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/core/deps.py): `backend/app/core/deps.py`
- [Thread state](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/core/threads.py): `backend/app/core/threads.py`
- [Agent state](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/models/state.py): `backend/app/models/state.py`

### Agent workflow

- [Graph builder](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/graph/builder.py): `backend/app/graph/builder.py`
- [Conditional routing](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/graph/edges/conditional.py): `backend/app/graph/edges/conditional.py`
- [Workflow stages](https://github.com/yogendrachukka01/adaptiveagent/tree/main/backend/app/graph/nodes): `backend/app/graph/nodes`
- [Retrieval stage](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/graph/nodes/retrieval_node.py): `backend/app/graph/nodes/retrieval_node.py`
- [Response stage](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/graph/nodes/response_node.py): `backend/app/graph/nodes/response_node.py`
- [Evaluation stage](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/graph/nodes/eval_node.py): `backend/app/graph/nodes/eval_node.py`
- [Refine stage](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/graph/nodes/refine_node.py): `backend/app/graph/nodes/refine_node.py`

### AI and retrieval

- [Query validation](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/services/validator/validator.py): `backend/app/services/validator/validator.py`
- [Hybrid search](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/services/retrieval/hybrid_search.py): `backend/app/services/retrieval/hybrid_search.py`
- [LLM providers](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/services/llm.py): `backend/app/services/llm.py`
- [Conversation memory](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/services/memory/memory.py): `backend/app/services/memory/memory.py`
- [Memory distiller](https://github.com/yogendrachukka01/adaptiveagent/blob/main/backend/app/services/memory/memory_worker.py): `backend/app/services/memory/memory_worker.py`
- [Vector stores](https://github.com/yogendrachukka01/adaptiveagent/tree/main/backend/app/services/retrieval/vector_store): `backend/app/services/retrieval/vector_store`

### Other components

- **User**
- **Streamed answer**
- **Knowledge document**

## Connections

- User → Chat interface: asks query
- Chat interface → API client: requests stream (evidence: `frontend/src/app/page.tsx`)
- API client → Chat API: sends SSE request
- Chat API → Graph builder: invokes graph (evidence: `backend/app/api/chat.py`)
- Graph builder → Workflow stages: registers stages (evidence: `backend/app/graph/builder.py`)
- Graph builder → Conditional routing: configures routing (evidence: `backend/app/graph/builder.py`)
- Graph builder → Retrieval stage: registers retrieval (evidence: `backend/app/graph/builder.py`)
- Graph builder → Response stage: registers response (evidence: `backend/app/graph/builder.py`)
- Graph builder → Evaluation stage: registers evaluation (evidence: `backend/app/graph/builder.py`)
- Graph builder → Refine stage: registers refinement (evidence: `backend/app/graph/builder.py`)
- Workflow stages → Query validation: validates query
- Retrieval stage → Hybrid search: searches evidence (evidence: `backend/app/graph/nodes/retrieval_node.py`)
- Retrieval stage → Vector stores: retrieves candidates
- Workflow stages → LLM providers: uses providers
- Response stage → Evaluation stage: evaluates output (evidence: `backend/app/graph/builder.py`)
- Evaluation stage → Refine stage: routes low scores (evidence: `backend/app/graph/builder.py`)
- Refine stage → Retrieval stage: retries retrieval (evidence: `backend/app/graph/builder.py`)
- Chat API → Streamed answer: streams response
- Streamed answer → API client: delivers SSE
- API client → Chat interface: yields events (evidence: `frontend/src/app/page.tsx`)
- Chat interface → Message display: renders messages (evidence: `frontend/src/app/page.tsx`)
- User → Knowledge document: uploads document
- Chat interface → API client: uploads file (evidence: `frontend/src/app/page.tsx`)
- API client → Upload API: posts file
- Chat API → API key auth: checks API key (evidence: `backend/app/api/chat.py`)
- Chat API → Thread state: uses thread state (evidence: `backend/app/api/chat.py`)
- Chat API → Conversation memory: stores conversation (evidence: `backend/app/api/chat.py`)
- Memory distiller → Conversation memory: reads conversations (evidence: `backend/app/services/memory/memory_worker.py`)
- Memory distiller → LLM providers: extracts facts (evidence: `backend/app/services/memory/memory_worker.py`)
- Memory distiller → Vector stores: stores distilled facts
