# jiabinfeng-commit/selfevolvingragagent architecture

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

- Interactive diagram: https://gitdiagram.com/jiabinfeng-commit/selfevolvingragagent
- Repository: https://github.com/jiabinfeng-commit/selfevolvingragagent

## Overview

This is a self-evolving RAG application: documents are parsed, chunked, embedded, and stored; users retrieve relevant passages and receive LLM answers, with optional reflection, tracing, and knowledge-gap healing. The React UI exposes knowledge-base management, chat, retrieval testing, health checks, and traces; the HTTP API connects those pages to the core. PostgreSQL stores source text and metadata, while Milvus stores vectors. The README documents evaluation and self-healing capabilities. Some internal paths are inferred only from the SOURCE INDEX; unverified links are omitted.

Main entry points: [`core/rag.py`](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/rag.py) (RAG orchestration), [`frontend/src/App.jsx`](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/App.jsx) (Page routing), [`core/retrieval.py`](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/retrieval.py) (Hybrid retrieval), [`core/agent.py`](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/agent.py) (Self-healing agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_app["Page routing<br/>[App.jsx]"]
  node_knowledge_ui["Knowledge base<br/>[KnowledgeBase.jsx]"]
  node_chat_ui["Chat<br/>[Chat.jsx]"]
  node_retrieval_ui["Retrieval test<br/>[Retrieval.jsx]"]
  node_health_ui["Health dashboard<br/>[Health.jsx]"]
  node_traces_ui["Trace viewer<br/>[Traces.jsx]"]
  node_frontend_api["API client<br/>[api.js]"]
end

subgraph group_service["API and ingestion"]
  node_http_api["HTTP API<br/>[api.py]"]
  node_ingestion["Document ingestion<br/>[ingest.py]"]
  node_chunking["Chunking<br/>[chunker.py]"]
end

subgraph group_rag["Retrieval and answering"]
  node_embedding["Embedding<br/>[embedder.py]"]
  node_rag_core["RAG orchestration<br/>[rag.py]"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_bm25["BM25 search<br/>[bm25.py]"]
  node_reranker["Result reranking<br/>[reranker.py]"]
  node_prompt["Prompt construction<br/>[prompt.py]"]
  node_llm["LLM client<br/>[llm.py]"]
  node_reflexion["Answer reflection<br/>[reflexion.py]"]
end

subgraph group_knowledge["Knowledge operations"]
  node_agent["Self-healing agent<br/>[agent.py]"]
  node_health["Knowledge health<br/>[health_check.py]"]
  node_evaluator["RAG evaluator<br/>[evaluator.py]"]
end

subgraph group_state["Storage and observability"]
  node_pg[("PostgreSQL<br/>[pg_store.py]")]
  node_vectors[("Milvus vector store<br/>[vec_store.py]")]
  node_tracing["Trace recording<br/>[tracing.py]"]
end

node_user(("User"))
node_external_docs(("External documentation"))
node_llm_provider(("LLM provider"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_knowledge_ui
node_app -->|"routes to"| node_chat_ui
node_app -->|"routes to"| node_retrieval_ui
node_app -->|"routes to"| node_health_ui
node_app -->|"routes to"| node_traces_ui
node_knowledge_ui -->|"requests"| node_frontend_api
node_chat_ui -->|"requests"| node_frontend_api
node_retrieval_ui -->|"requests"| node_frontend_api
node_health_ui -->|"requests"| node_frontend_api
node_traces_ui -->|"requests"| node_frontend_api
node_frontend_api -->|"calls"| node_http_api
node_http_api -->|"calls"| node_ingestion
node_http_api -->|"calls"| node_rag_core
node_http_api -->|"calls"| node_health
node_http_api -->|"calls"| node_agent
node_ingestion -->|"chunks"| node_chunking
node_ingestion -->|"encodes"| node_embedding
node_ingestion -->|"writes"| node_pg
node_ingestion -->|"writes"| node_vectors
node_rag_core -->|"retrieves"| node_retrieval
node_retrieval -->|"encodes query"| node_embedding
node_retrieval -->|"searches"| node_vectors
node_retrieval -->|"loads passages"| node_pg
node_retrieval -->|"reranks"| node_reranker
node_rag_core -->|"builds index"| node_bm25
node_rag_core -->|"builds prompt"| node_prompt
node_rag_core -->|"generates answer"| node_llm
node_llm -->|"sends request"| node_llm_provider
node_rag_core -->|"reflects answer"| node_reflexion
node_rag_core -->|"heals gaps"| node_agent
node_agent -->|"researches"| node_external_docs
node_agent -->|"stages knowledge"| node_pg
node_agent -->|"stages vectors"| node_vectors
node_rag_core -->|"saves answers"| node_pg
node_rag_core -->|"records trace"| node_tracing
node_health -->|"checks"| node_pg
node_health -->|"checks"| node_vectors
node_evaluator -->|"evaluates"| node_retrieval
node_evaluator -->|"evaluates healing"| node_agent

click node_app "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/App.jsx"
click node_knowledge_ui "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/components/KnowledgeBase.jsx"
click node_chat_ui "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/components/Chat.jsx"
click node_retrieval_ui "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/components/Retrieval.jsx"
click node_health_ui "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/components/Health.jsx"
click node_traces_ui "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/components/Traces.jsx"
click node_frontend_api "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/api.js"
click node_http_api "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/scripts/api.py"
click node_ingestion "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/ingest.py"
click node_chunking "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/chunker.py"
click node_embedding "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/embedder.py"
click node_rag_core "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/rag.py"
click node_retrieval "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/retrieval.py"
click node_bm25 "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/bm25.py"
click node_reranker "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/reranker.py"
click node_prompt "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/prompt.py"
click node_llm "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/llm.py"
click node_reflexion "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/reflexion.py"
click node_agent "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/agent.py"
click node_health "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/health_check.py"
click node_evaluator "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/evaluator.py"
click node_pg "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/storage/pg_store.py"
click node_vectors "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/storage/vec_store.py"
click node_tracing "https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/tracing.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_app,node_knowledge_ui,node_chat_ui,node_retrieval_ui,node_health_ui,node_traces_ui,node_frontend_api,node_user toneBlue
class node_http_api,node_ingestion,node_chunking toneAmber
class node_embedding,node_rag_core,node_retrieval,node_bm25,node_reranker,node_prompt,node_llm,node_reflexion toneMint
class node_agent,node_health,node_evaluator toneRose
class node_pg,node_vectors,node_tracing,node_external_docs,node_llm_provider toneIndigo
```

## Components

### User interface

- [Page routing](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Knowledge base](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/components/KnowledgeBase.jsx): `frontend/src/components/KnowledgeBase.jsx`
- [Chat](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/components/Chat.jsx): `frontend/src/components/Chat.jsx`
- [Retrieval test](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/components/Retrieval.jsx): `frontend/src/components/Retrieval.jsx`
- [Health dashboard](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/components/Health.jsx): `frontend/src/components/Health.jsx`
- [Trace viewer](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/components/Traces.jsx): `frontend/src/components/Traces.jsx`
- [API client](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/frontend/src/api.js): `frontend/src/api.js`

### API and ingestion

- [HTTP API](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/scripts/api.py): `scripts/api.py`
- [Document ingestion](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/ingest.py): `core/ingest.py`
- [Chunking](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/chunker.py): `core/chunker.py`

### Retrieval and answering

- [Embedding](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/embedder.py): `core/embedder.py`
- [RAG orchestration](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/rag.py): `core/rag.py`
- [Hybrid retrieval](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/retrieval.py): `core/retrieval.py`
- [BM25 search](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/bm25.py): `core/bm25.py`
- [Result reranking](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/reranker.py): `core/reranker.py`
- [Prompt construction](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/prompt.py): `core/prompt.py`
- [LLM client](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/llm.py): `core/llm.py`
- [Answer reflection](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/reflexion.py): `core/reflexion.py`

### Knowledge operations

- [Self-healing agent](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/agent.py): `core/agent.py`
- [Knowledge health](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/health_check.py): `core/health_check.py`
- [RAG evaluator](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/evaluator.py): `core/evaluator.py`

### Storage and observability

- [PostgreSQL](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/storage/pg_store.py): `core/storage/pg_store.py`
- [Milvus vector store](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/storage/vec_store.py): `core/storage/vec_store.py`
- [Trace recording](https://github.com/jiabinfeng-commit/selfevolvingragagent/blob/main/core/tracing.py): `core/tracing.py`

### Other components

- **User**
- **External documentation**
- **LLM provider**

## Connections

- User → Page routing: uses (evidence: `frontend/src/App.jsx`)
- Page routing → Knowledge base: routes to (evidence: `frontend/src/App.jsx`)
- Page routing → Chat: routes to (evidence: `frontend/src/App.jsx`)
- Page routing → Retrieval test: routes to (evidence: `frontend/src/App.jsx`)
- Page routing → Health dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Page routing → Trace viewer: routes to (evidence: `frontend/src/App.jsx`)
- Knowledge base → API client: requests (evidence: `frontend/src/components/KnowledgeBase.jsx`)
- Chat → API client: requests (evidence: `frontend/src/components/Chat.jsx`)
- Retrieval test → API client: requests (evidence: `frontend/src/components/Retrieval.jsx`)
- Health dashboard → API client: requests (evidence: `frontend/src/components/Health.jsx`)
- Trace viewer → API client: requests (evidence: `frontend/src/components/Traces.jsx`)
- API client → HTTP API: calls (evidence: `README.md`)
- HTTP API → Document ingestion: calls (evidence: `README.md`)
- HTTP API → RAG orchestration: calls (evidence: `scripts/api.py`)
- HTTP API → Knowledge health: calls (evidence: `scripts/api.py`)
- HTTP API → Self-healing agent: calls (evidence: `scripts/api.py`)
- Document ingestion → Chunking: chunks (evidence: `core/ingest.py`)
- Document ingestion → Embedding: encodes (evidence: `core/ingest.py`)
- Document ingestion → PostgreSQL: writes (evidence: `core/ingest.py`)
- Document ingestion → Milvus vector store: writes (evidence: `core/ingest.py`)
- RAG orchestration → Hybrid retrieval: retrieves (evidence: `core/rag.py`)
- Hybrid retrieval → Embedding: encodes query (evidence: `core/retrieval.py`)
- Hybrid retrieval → Milvus vector store: searches (evidence: `core/retrieval.py`)
- Hybrid retrieval → PostgreSQL: loads passages (evidence: `core/retrieval.py`)
- Hybrid retrieval → Result reranking: reranks (evidence: `core/retrieval.py`)
- RAG orchestration → BM25 search: builds index (evidence: `core/rag.py`)
- RAG orchestration → Prompt construction: builds prompt (evidence: `core/rag.py`)
- RAG orchestration → LLM client: generates answer (evidence: `core/rag.py`)
- LLM client → LLM provider: sends request (evidence: `core/llm.py`)
- RAG orchestration → Answer reflection: reflects answer (evidence: `core/rag.py`)
- RAG orchestration → Self-healing agent: heals gaps (evidence: `core/rag.py`)
- Self-healing agent → External documentation: researches (evidence: `README.md`)
- Self-healing agent → PostgreSQL: stages knowledge (evidence: `core/agent.py`)
- Self-healing agent → Milvus vector store: stages vectors (evidence: `core/agent.py`)
- RAG orchestration → PostgreSQL: saves answers (evidence: `core/rag.py`)
- RAG orchestration → Trace recording: records trace (evidence: `core/rag.py`)
- Knowledge health → PostgreSQL: checks (evidence: `core/health_check.py`)
- Knowledge health → Milvus vector store: checks (evidence: `core/health_check.py`)
- RAG evaluator → Hybrid retrieval: evaluates (evidence: `core/evaluator.py`)
- RAG evaluator → Self-healing agent: evaluates healing (evidence: `core/evaluator.py`)
