# zylon-ai/private-gpt architecture

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

- Interactive diagram: https://gitdiagram.com/zylon-ai/private-gpt
- Repository: https://github.com/zylon-ai/private-gpt

## Overview

PrivateGPT is an API layer for building private AI applications on OpenAI-compatible inference servers; it does not host models itself. The main workflow is a client request into the API, then chat orchestration and model/tool execution, with retrieval grounded by ingested files and artifacts. Separate branches provide embeddings, async ingestion, database/tabular tools, and MCP/custom-tool support. The README documents these capabilities; sampled source and the SOURCE INDEX support only some internal links, so undocumented wiring is omitted.

Main entry points: [`private_gpt/components/engines/chat/async_chat_engine.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/engines/chat/async_chat_engine.py) (Chat engine), [`private_gpt/server/ingest/ingest_service.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/ingest/ingest_service.py) (Ingestion service), [`private_gpt/components/ingestion/ingestion_scheduler.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/ingestion/ingestion_scheduler.py) (Ingestion scheduler), [`private_gpt/server/primitives/semantic_search_service.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/primitives/semantic_search_service.py) (Semantic search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and requests"]
  node_api["Messages API<br/>[chat_router.py]"]
  node_asyncapi["Async chat API"]
  node_ingestapi["Ingestion API<br/>[ingest_router.py]"]
  node_embapi["Embeddings API"]
end

subgraph group_chat["Chat and tools"]
  node_chatengine["Chat engine"]
  node_chatconfig["Chat configuration"]
  node_dbprocessor["Database tool processor"]
  node_dbbuilder["Database tool builder"]
  node_dbquery["Database query engine"]
  node_websearch["Web search"]
  node_codeexec["Code execution"]
  node_mcp["MCP service<br/>[mcp_service.py]"]
end

subgraph group_knowledge["Knowledge and ingestion"]
  node_ingestscheduler["Ingestion scheduler"]
  node_ingestservice["Ingestion service<br/>[ingest_service.py]"]
  node_parse["Document parsing<br/>[parse_component.py]"]
  node_ingest["Ingest processing"]
  node_artifactindex[("Artifact index")]
  node_semantic["Semantic search"]
end

subgraph group_platform["Models and services"]
  node_embeddings["Embedding service"]
  node_llm["LLM component<br/>[llm_component.py]"]
  node_nodestore[("Node store")]
  node_worker["Background worker<br/>[celery.py]"]
end

node_client(("Application client"))
node_inference["OpenAI-compatible server"]
node_externaltools["External tools / MCP servers"]

node_client -->|"sends messages"| node_api
node_client -->|"requests async"| node_asyncapi
node_api -.->|"runs chat"| node_chatengine
node_asyncapi -.->|"runs chat"| node_chatengine
node_chatengine -.->|"invokes model"| node_llm
node_llm -->|"calls inference"| node_inference
node_chatengine -.->|"resolves tools"| node_dbprocessor
node_dbprocessor -->|"builds tool"| node_dbbuilder
node_dbbuilder -->|"queries database"| node_dbquery
node_chatengine -.->|"offers search"| node_websearch
node_chatengine -.->|"offers execution"| node_codeexec
node_chatengine -.->|"supports MCP"| node_mcp
node_mcp -->|"connects servers"| node_externaltools
node_client -->|"uploads content"| node_ingestapi
node_ingestapi -->|"schedules ingestion"| node_ingestscheduler
node_ingestscheduler -.->|"dispatches tasks"| node_worker
node_ingestscheduler -.->|"processes request"| node_ingestservice
node_ingestservice -->|"parses documents"| node_parse
node_ingestservice -->|"ingests documents"| node_ingest
node_ingestservice -->|"populates index"| node_artifactindex
node_artifactindex -->|"reads nodes"| node_nodestore
node_client -->|"requests retrieval"| node_semantic
node_semantic -->|"creates embeddings"| node_embeddings
node_semantic -->|"searches index"| node_artifactindex
node_client -->|"requests embeddings"| node_embapi
node_embapi -->|"creates embeddings"| node_embeddings
node_client -->|"uses API"| node_externaltools

click node_api "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/chat/chat_router.py"
click node_asyncapi "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/chat_async/chat_async_router.py"
click node_ingestapi "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/ingest/ingest_router.py"
click node_embapi "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/embeddings/embeddings_router.py"
click node_chatengine "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/engines/chat/async_chat_engine.py"
click node_chatconfig "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/chat/models/chat_config_models.py"
click node_dbprocessor "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/tools/processors/database_query_processor.py"
click node_dbbuilder "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/tools/builders/database_query_builder.py"
click node_dbquery "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/tabular/database_query_generator.py"
click node_websearch "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/web/web_search/web_search_service.py"
click node_codeexec "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/code_execution/code_execution_component.py"
click node_mcp "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/mcp/mcp_service.py"
click node_ingestscheduler "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/ingestion/ingestion_scheduler.py"
click node_ingestservice "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/ingest/ingest_service.py"
click node_parse "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/ingest/parse_component.py"
click node_ingest "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/ingest/ingest_component.py"
click node_artifactindex "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/artifact_index/base_artifact_index.py"
click node_semantic "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/primitives/semantic_search_service.py"
click node_embeddings "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/embedding/embedding_component.py"
click node_llm "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/llm/llm_component.py"
click node_nodestore "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/node_store/node_store_component.py"
click node_worker "https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/celery/celery.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,node_asyncapi,node_ingestapi,node_embapi,node_client toneBlue
class node_chatengine,node_chatconfig,node_dbprocessor,node_dbbuilder,node_dbquery,node_websearch,node_codeexec,node_mcp toneAmber
class node_ingestscheduler,node_ingestservice,node_parse,node_ingest,node_artifactindex,node_semantic,node_inference,node_externaltools toneMint
class node_embeddings,node_llm,node_nodestore,node_worker toneRose
```

## Components

### API and requests

- [Messages API](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/chat/chat_router.py): `private_gpt/server/chat/chat_router.py`
- [Async chat API](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/chat_async/chat_async_router.py): `private_gpt/server/chat_async/chat_async_router.py`
- [Ingestion API](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/ingest/ingest_router.py): `private_gpt/server/ingest/ingest_router.py`
- [Embeddings API](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/embeddings/embeddings_router.py): `private_gpt/server/embeddings/embeddings_router.py`

### Chat and tools

- [Chat engine](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/engines/chat/async_chat_engine.py): `private_gpt/components/engines/chat/async_chat_engine.py`
- [Chat configuration](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/chat/models/chat_config_models.py): `private_gpt/components/chat/models/chat_config_models.py`
- [Database tool processor](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/tools/processors/database_query_processor.py): `private_gpt/components/tools/processors/database_query_processor.py`
- [Database tool builder](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/tools/builders/database_query_builder.py): `private_gpt/components/tools/builders/database_query_builder.py`
- [Database query engine](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/tabular/database_query_generator.py): `private_gpt/components/tabular/database_query_generator.py`
- [Web search](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/web/web_search/web_search_service.py): `private_gpt/components/web/web_search/web_search_service.py`
- [Code execution](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/code_execution/code_execution_component.py): `private_gpt/components/code_execution/code_execution_component.py`
- [MCP service](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/mcp/mcp_service.py): `private_gpt/server/mcp/mcp_service.py`

### Knowledge and ingestion

- [Ingestion scheduler](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/ingestion/ingestion_scheduler.py): `private_gpt/components/ingestion/ingestion_scheduler.py`
- [Ingestion service](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/ingest/ingest_service.py): `private_gpt/server/ingest/ingest_service.py`
- [Document parsing](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/ingest/parse_component.py): `private_gpt/components/ingest/parse_component.py`
- [Ingest processing](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/ingest/ingest_component.py): `private_gpt/components/ingest/ingest_component.py`
- [Artifact index](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/artifact_index/base_artifact_index.py): `private_gpt/artifact_index/base_artifact_index.py`
- [Semantic search](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/server/primitives/semantic_search_service.py): `private_gpt/server/primitives/semantic_search_service.py`

### Models and services

- [Embedding service](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/embedding/embedding_component.py): `private_gpt/components/embedding/embedding_component.py`
- [LLM component](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/llm/llm_component.py): `private_gpt/components/llm/llm_component.py`
- [Node store](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/node_store/node_store_component.py): `private_gpt/components/node_store/node_store_component.py`
- [Background worker](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/celery/celery.py): `private_gpt/celery/celery.py`

### Other components

- **Application client**
- **OpenAI-compatible server**
- **External tools / MCP servers**

## Connections

- Application client → Messages API: sends messages
- Application client → Async chat API: requests async
- Messages API → Chat engine: runs chat
- Async chat API → Chat engine: runs chat
- Chat engine → LLM component: invokes model (evidence: `private_gpt/components/engines/chat/async_chat_engine.py`)
- LLM component → OpenAI-compatible server: calls inference
- Chat engine → Database tool processor: resolves tools
- Database tool processor → Database tool builder: builds tool (evidence: `private_gpt/components/tools/processors/database_query_processor.py`)
- Database tool builder → Database query engine: queries database (evidence: `private_gpt/components/tools/builders/database_query_builder.py`)
- Chat engine → Web search: offers search
- Chat engine → Code execution: offers execution
- Chat engine → MCP service: supports MCP
- MCP service → External tools / MCP servers: connects servers
- Application client → Ingestion API: uploads content
- Ingestion API → Ingestion scheduler: schedules ingestion (evidence: `private_gpt/server/ingest/ingest_router.py`)
- Ingestion scheduler → Background worker: dispatches tasks
- Ingestion scheduler → Ingestion service: processes request
- Ingestion service → Document parsing: parses documents (evidence: `private_gpt/server/ingest/ingest_service.py`)
- Ingestion service → Ingest processing: ingests documents (evidence: `private_gpt/server/ingest/ingest_service.py`)
- Ingestion service → Artifact index: populates index (evidence: `private_gpt/server/ingest/ingest_service.py`)
- Artifact index → Node store: reads nodes (evidence: `private_gpt/artifact_index/base_artifact_index.py`)
- Application client → Semantic search: requests retrieval
- Semantic search → Embedding service: creates embeddings (evidence: `private_gpt/server/primitives/semantic_search_service.py`)
- Semantic search → Artifact index: searches index (evidence: `private_gpt/server/primitives/semantic_search_service.py`)
- Application client → Embeddings API: requests embeddings
- Embeddings API → Embedding service: creates embeddings
- Application client → External tools / MCP servers: uses API
