# apecloud/aperag architecture

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

- Interactive diagram: https://gitdiagram.com/apecloud/aperag
- Repository: https://github.com/apecloud/aperag

## Overview

ApeRAG is a RAG platform for building and querying knowledge collections, with a web/API interface, document ingestion and multimodal parsing, five retrieval index types, agent-assisted answers, and enterprise management. A typical workflow starts with a user adding documents to a collection; ingestion parses and indexes them, then chat or search retrieves relevant material for an answer. The graph also preserves documented branches for graph normalization, MCP access, web search, workflows, evaluation, and administration. Several links reflect README-level capabilities because the relevant runtime files were not sampled.

Main entry points: [`aperag/service/agent_chat_service.py`](https://github.com/apecloud/aperag/blob/main/aperag/service/agent_chat_service.py) (Agent Chat), [`aperag/views/collections.py`](https://github.com/apecloud/aperag/blob/main/aperag/views/collections.py) (Collection API), [`aperag/app.py`](https://github.com/apecloud/aperag/blob/main/aperag/app.py) (FastAPI Routes), [`aperag/service/document_service.py`](https://github.com/apecloud/aperag/blob/main/aperag/service/document_service.py) (Document Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Services"]
  node_api_views["FastAPI Routes<br/>[app.py]"]
  node_collection_routes["Collection API<br/>[collections.py]"]
  node_auth_routes["Authentication API<br/>[auth.py]"]
  node_collection_service["Collection Services"]
end

subgraph group_ingest["Collection Ingestion"]
  node_document_service["Document Service"]
  node_source_connectors["Source Connectors<br/>[base.py]"]
  node_document_parser["Document Parsing<br/>[doc_parser.py]"]
  node_index_manager["Index Manager<br/>[manager.py]"]
  node_index_types["Five Index Types"]
  node_graph_manager["Graph Indexing"]
  node_graph_engine["LightRAG Engine<br/>[base.py]"]
end

subgraph group_retrieve["Retrieval and Agents"]
  node_agent_chat["Agent Chat"]
  node_agent_sessions["Agent Sessions"]
  node_search_query["Search and Query<br/>[query.py]"]
  node_flow_engine["Agent Workflow Engine<br/>[engine.py]"]
  node_mcp_server["MCP Server<br/>[server.py]"]
  node_web_search_service["Web Search<br/>[search_service.py]"]
end

subgraph group_platform["Data and Models"]
  node_database[("Relational Data<br/>[models.py]")]
  node_database_ops["Database Operations<br/>[ops.py]"]
  node_llm_services["LLM Services"]
  node_vector_store[("Vector Store<br/>[connector.py]")]
  node_schema["API and Flow Schemas<br/>[view_models.py]"]
end

subgraph group_capabilities["Product Capabilities"]
  node_audit["Audit Logging<br/>[audit_decorator.py]"]
  node_summary["Summary Indexing"]
  node_evaluation["Evaluation"]
  node_marketplace["Marketplace"]
end

node_user(("User"))
node_mcp_client(("MCP Client"))
node_web_search["Web Search Providers"]

node_user -->|"uses"| node_api_views
node_api_views -->|"routes"| node_collection_routes
node_user -->|"manages collections"| node_collection_routes
node_collection_routes -->|"delegates"| node_collection_service
node_collection_routes -->|"delegates"| node_document_service
node_user -->|"authenticates"| node_auth_routes
node_document_service -.->|"acquires documents"| node_source_connectors
node_source_connectors -.->|"supplies content"| node_document_parser
node_document_service -.->|"indexes documents"| node_index_manager
node_index_manager -.->|"coordinates"| node_index_types
node_graph_manager -->|"builds graph index"| node_graph_engine
node_graph_engine -.->|"uses language models"| node_llm_services
node_user -->|"asks questions"| node_agent_chat
node_agent_chat -.->|"manages sessions"| node_agent_sessions
node_agent_chat -.->|"retrieves context"| node_search_query
node_search_query -->|"hybrid retrieval"| node_index_types
node_agent_chat -->|"searches web"| node_web_search_service
node_web_search_service -->|"queries providers"| node_web_search
node_agent_chat -.->|"generates answers"| node_llm_services
node_user -->|"configures workflows"| node_flow_engine
node_mcp_client -->|"connects"| node_mcp_server
node_mcp_server -->|"offers hybrid search"| node_search_query
node_database_ops -.->|"reads and writes"| node_database
node_database_ops -->|"composes repositories"| node_database
node_index_types -.->|"stores vectors"| node_vector_store
node_api_views -.->|"validates requests"| node_schema
node_collection_routes -->|"audits actions"| node_audit
node_collection_service -.->|"generates summaries"| node_summary
node_user -->|"evaluates answers"| node_evaluation
node_user -->|"explores collections"| node_marketplace

click node_api_views "https://github.com/apecloud/aperag/blob/main/aperag/app.py"
click node_collection_routes "https://github.com/apecloud/aperag/blob/main/aperag/views/collections.py"
click node_auth_routes "https://github.com/apecloud/aperag/blob/main/aperag/views/auth.py"
click node_collection_service "https://github.com/apecloud/aperag/blob/main/aperag/service/collection_service.py"
click node_document_service "https://github.com/apecloud/aperag/blob/main/aperag/service/document_service.py"
click node_source_connectors "https://github.com/apecloud/aperag/blob/main/aperag/source/base.py"
click node_document_parser "https://github.com/apecloud/aperag/blob/main/aperag/docparser/doc_parser.py"
click node_index_manager "https://github.com/apecloud/aperag/blob/main/aperag/index/manager.py"
click node_index_types "https://github.com/apecloud/aperag/tree/main/aperag/index"
click node_graph_manager "https://github.com/apecloud/aperag/blob/main/aperag/graph/lightrag_manager.py"
click node_graph_engine "https://github.com/apecloud/aperag/blob/main/aperag/graph/lightrag/base.py"
click node_agent_chat "https://github.com/apecloud/aperag/blob/main/aperag/service/agent_chat_service.py"
click node_agent_sessions "https://github.com/apecloud/aperag/blob/main/aperag/agent/agent_session_manager.py"
click node_search_query "https://github.com/apecloud/aperag/blob/main/aperag/query/query.py"
click node_flow_engine "https://github.com/apecloud/aperag/blob/main/aperag/flow/engine.py"
click node_mcp_server "https://github.com/apecloud/aperag/blob/main/aperag/mcp/server.py"
click node_web_search_service "https://github.com/apecloud/aperag/blob/main/aperag/websearch/search/search_service.py"
click node_database "https://github.com/apecloud/aperag/blob/main/aperag/db/models.py"
click node_database_ops "https://github.com/apecloud/aperag/blob/main/aperag/db/ops.py"
click node_llm_services "https://github.com/apecloud/aperag/blob/main/aperag/llm/completion/completion_service.py"
click node_vector_store "https://github.com/apecloud/aperag/blob/main/aperag/vectorstore/connector.py"
click node_audit "https://github.com/apecloud/aperag/blob/main/aperag/utils/audit_decorator.py"
click node_summary "https://github.com/apecloud/aperag/blob/main/aperag/service/collection_summary_service.py"
click node_evaluation "https://github.com/apecloud/aperag/blob/main/aperag/service/evaluation_service.py"
click node_marketplace "https://github.com/apecloud/aperag/blob/main/aperag/service/marketplace_service.py"
click node_schema "https://github.com/apecloud/aperag/blob/main/aperag/schema/view_models.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_api_views,node_collection_routes,node_auth_routes,node_collection_service,node_user,node_mcp_client toneBlue
class node_document_service,node_source_connectors,node_document_parser,node_index_manager,node_index_types,node_graph_manager,node_graph_engine toneAmber
class node_agent_chat,node_agent_sessions,node_search_query,node_flow_engine,node_mcp_server,node_web_search_service toneMint
class node_database,node_database_ops,node_llm_services,node_vector_store,node_schema toneRose
class node_audit,node_summary,node_evaluation,node_marketplace,node_web_search toneIndigo
```

## Components

### API and Services

- [FastAPI Routes](https://github.com/apecloud/aperag/blob/main/aperag/app.py): `aperag/app.py`
- [Collection API](https://github.com/apecloud/aperag/blob/main/aperag/views/collections.py): `aperag/views/collections.py`
- [Authentication API](https://github.com/apecloud/aperag/blob/main/aperag/views/auth.py): `aperag/views/auth.py`
- [Collection Services](https://github.com/apecloud/aperag/blob/main/aperag/service/collection_service.py): `aperag/service/collection_service.py`

### Collection Ingestion

- [Document Service](https://github.com/apecloud/aperag/blob/main/aperag/service/document_service.py): `aperag/service/document_service.py`
- [Source Connectors](https://github.com/apecloud/aperag/blob/main/aperag/source/base.py): `aperag/source/base.py`
- [Document Parsing](https://github.com/apecloud/aperag/blob/main/aperag/docparser/doc_parser.py): `aperag/docparser/doc_parser.py`
- [Index Manager](https://github.com/apecloud/aperag/blob/main/aperag/index/manager.py): `aperag/index/manager.py`
- [Five Index Types](https://github.com/apecloud/aperag/tree/main/aperag/index): `aperag/index`
- [Graph Indexing](https://github.com/apecloud/aperag/blob/main/aperag/graph/lightrag_manager.py): `aperag/graph/lightrag_manager.py`
- [LightRAG Engine](https://github.com/apecloud/aperag/blob/main/aperag/graph/lightrag/base.py): `aperag/graph/lightrag/base.py`

### Retrieval and Agents

- [Agent Chat](https://github.com/apecloud/aperag/blob/main/aperag/service/agent_chat_service.py): `aperag/service/agent_chat_service.py`
- [Agent Sessions](https://github.com/apecloud/aperag/blob/main/aperag/agent/agent_session_manager.py): `aperag/agent/agent_session_manager.py`
- [Search and Query](https://github.com/apecloud/aperag/blob/main/aperag/query/query.py): `aperag/query/query.py`
- [Agent Workflow Engine](https://github.com/apecloud/aperag/blob/main/aperag/flow/engine.py): `aperag/flow/engine.py`
- [MCP Server](https://github.com/apecloud/aperag/blob/main/aperag/mcp/server.py): `aperag/mcp/server.py`
- [Web Search](https://github.com/apecloud/aperag/blob/main/aperag/websearch/search/search_service.py): `aperag/websearch/search/search_service.py`

### Data and Models

- [Relational Data](https://github.com/apecloud/aperag/blob/main/aperag/db/models.py): `aperag/db/models.py`
- [Database Operations](https://github.com/apecloud/aperag/blob/main/aperag/db/ops.py): `aperag/db/ops.py`
- [LLM Services](https://github.com/apecloud/aperag/blob/main/aperag/llm/completion/completion_service.py): `aperag/llm/completion/completion_service.py`
- [Vector Store](https://github.com/apecloud/aperag/blob/main/aperag/vectorstore/connector.py): `aperag/vectorstore/connector.py`
- [API and Flow Schemas](https://github.com/apecloud/aperag/blob/main/aperag/schema/view_models.py): `aperag/schema/view_models.py`

### Product Capabilities

- [Audit Logging](https://github.com/apecloud/aperag/blob/main/aperag/utils/audit_decorator.py): `aperag/utils/audit_decorator.py`
- [Summary Indexing](https://github.com/apecloud/aperag/blob/main/aperag/service/collection_summary_service.py): `aperag/service/collection_summary_service.py`
- [Evaluation](https://github.com/apecloud/aperag/blob/main/aperag/service/evaluation_service.py): `aperag/service/evaluation_service.py`
- [Marketplace](https://github.com/apecloud/aperag/blob/main/aperag/service/marketplace_service.py): `aperag/service/marketplace_service.py`

### Other components

- **User**
- **MCP Client**
- **Web Search Providers**

## Connections

- User → FastAPI Routes: uses (evidence: `README.md`)
- FastAPI Routes → Collection API: routes (evidence: `aperag/app.py`)
- User → Collection API: manages collections (evidence: `README.md`)
- Collection API → Collection Services: delegates (evidence: `aperag/views/collections.py`)
- Collection API → Document Service: delegates (evidence: `aperag/views/collections.py`)
- User → Authentication API: authenticates (evidence: `README.md`)
- Document Service → Source Connectors: acquires documents
- Source Connectors → Document Parsing: supplies content
- Document Service → Index Manager: indexes documents
- Index Manager → Five Index Types: coordinates
- Graph Indexing → LightRAG Engine: builds graph index (evidence: `aperag/graph/lightrag_manager.py`)
- LightRAG Engine → LLM Services: uses language models
- User → Agent Chat: asks questions (evidence: `README.md`)
- Agent Chat → Agent Sessions: manages sessions
- Agent Chat → Search and Query: retrieves context
- Search and Query → Five Index Types: hybrid retrieval (evidence: `README.md`)
- Agent Chat → Web Search: searches web (evidence: `README.md`)
- Web Search → Web Search Providers: queries providers (evidence: `aperag/websearch/search/search_service.py`)
- Agent Chat → LLM Services: generates answers
- User → Agent Workflow Engine: configures workflows (evidence: `README.md`)
- MCP Client → MCP Server: connects (evidence: `README.md`)
- MCP Server → Search and Query: offers hybrid search (evidence: `README.md`)
- Database Operations → Relational Data: reads and writes
- Database Operations → Relational Data: composes repositories (evidence: `aperag/db/ops.py`)
- Five Index Types → Vector Store: stores vectors
- FastAPI Routes → API and Flow Schemas: validates requests
- Collection API → Audit Logging: audits actions (evidence: `aperag/views/collections.py`)
- Collection Services → Summary Indexing: generates summaries
- User → Evaluation: evaluates answers (evidence: `README.md`)
- User → Marketplace: explores collections (evidence: `README.md`)