# arc53/docsgpt architecture

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

- Interactive diagram: https://gitdiagram.com/arc53/docsgpt
- Repository: https://github.com/arc53/docsgpt

## Overview

DocsGPT is a self-hosted, document-grounded agent platform. A user submits a question through the web app or an integration; the API runs an agent, retrieves knowledge, invokes models and tools, applies guardrails, and returns a cited answer. Separate capabilities cover knowledge ingestion and syncing, visual workflows, integrations, and team administration. The README documents the high-level API/worker/data flow; source-index references support several internal links. Other links reflect documented capabilities, not inspection of unsampled implementations.

Main entry points: [`docsgpt/app.py`](https://github.com/arc53/docsgpt/blob/main/docsgpt/app.py) (API routes), [`docsgpt/agents/agentic_agent.py`](https://github.com/arc53/docsgpt/blob/main/docsgpt/agents/agentic_agent.py) (Agent execution), [`docsgpt/worker.py`](https://github.com/arc53/docsgpt/blob/main/docsgpt/worker.py) (Background worker), [`docsgpt/parser/embedding_pipeline.py`](https://github.com/arc53/docsgpt/blob/main/docsgpt/parser/embedding_pipeline.py) (Document ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web app<br/>[App.tsx]"]
  node_widget["Chat widget<br/>[App.tsx]"]
  node_api["API routes<br/>[app.py]"]
  node_answer["Answer endpoint<br/>[answer.py]"]
  node_v1["OpenAI API<br/>[routes.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
end

subgraph group_knowledge["Knowledge pipeline"]
  node_search["Search service<br/>[search_service.py]"]
  node_retriever["Retrieval strategies<br/>[dispatcher.py]"]
  node_ingest["Document ingestion"]
  node_connectors["Knowledge connectors<br/>[service.py]"]
  node_worker["Background worker<br/>[worker.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Agent execution<br/>[agentic_agent.py]"]
  node_workflow["Workflow engine<br/>[workflow_engine.py]"]
  node_guard["Guardrails<br/>[engine.py]"]
  node_tools["Agent tools<br/>[default_tools.py]"]
  node_models["Model providers<br/>[llm_creator.py]"]
end

subgraph group_platform["Platform services"]
  node_db[("Postgres data<br/>[session.py]")]
  node_vectors[("Vector stores<br/>[vector_creator.py]")]
  node_files[("File storage<br/>[storage_creator.py]")]
end

subgraph group_operations["Administration"]
  node_auth["Identity and access<br/>[resource_access.py]"]
  node_teams["Teams and quotas<br/>[quotas.py]"]
  node_schedules["Schedules and webhooks<br/>[routes.py]"]
end

node_user(("User or client"))

node_user -->|"uses"| node_web
node_user -->|"uses"| node_widget
node_user -->|"requests"| node_api
node_user -->|"queries"| node_mcp
node_web -->|"calls"| node_api
node_widget -->|"calls"| node_api
node_api -.->|"routes"| node_answer
node_api -->|"routes"| node_v1
node_answer -.->|"runs"| node_agent
node_v1 -->|"runs"| node_agent
node_mcp -.->|"searches"| node_search
node_agent -.->|"retrieves"| node_search
node_search -->|"dispatches"| node_retriever
node_retriever -.->|"queries"| node_vectors
node_agent -.->|"invokes"| node_models
node_agent -.->|"executes"| node_tools
node_agent -.->|"checks"| node_guard
node_worker -.->|"runs"| node_ingest
node_connectors -.->|"syncs content"| node_ingest
node_ingest -->|"indexes"| node_vectors
node_ingest -->|"records progress"| node_db
node_worker -->|"uses"| node_db
node_worker -->|"uses"| node_vectors
node_worker -->|"uses"| node_files
node_api -->|"uses"| node_db
node_api -->|"uses"| node_vectors
node_api -->|"uses"| node_files
node_workflow -->|"runs nodes"| node_agent
node_workflow -.->|"uses"| node_tools
node_api -->|"checks access"| node_auth
node_api -.->|"administers"| node_teams
node_api -.->|"manages"| node_schedules

click node_web "https://github.com/arc53/docsgpt/blob/main/frontend/src/App.tsx"
click node_widget "https://github.com/arc53/docsgpt/blob/main/extensions/react-widget/src/App.tsx"
click node_api "https://github.com/arc53/docsgpt/blob/main/docsgpt/app.py"
click node_answer "https://github.com/arc53/docsgpt/blob/main/docsgpt/api/answer/routes/answer.py"
click node_v1 "https://github.com/arc53/docsgpt/blob/main/docsgpt/api/v1/routes.py"
click node_mcp "https://github.com/arc53/docsgpt/blob/main/docsgpt/mcp_server.py"
click node_agent "https://github.com/arc53/docsgpt/blob/main/docsgpt/agents/agentic_agent.py"
click node_workflow "https://github.com/arc53/docsgpt/blob/main/docsgpt/agents/workflows/workflow_engine.py"
click node_guard "https://github.com/arc53/docsgpt/blob/main/docsgpt/guardrails/engine.py"
click node_tools "https://github.com/arc53/docsgpt/blob/main/docsgpt/agents/default_tools.py"
click node_models "https://github.com/arc53/docsgpt/blob/main/docsgpt/llm/llm_creator.py"
click node_search "https://github.com/arc53/docsgpt/blob/main/docsgpt/services/search_service.py"
click node_retriever "https://github.com/arc53/docsgpt/blob/main/docsgpt/retriever/dispatcher.py"
click node_ingest "https://github.com/arc53/docsgpt/blob/main/docsgpt/parser/embedding_pipeline.py"
click node_connectors "https://github.com/arc53/docsgpt/blob/main/docsgpt/connectors/service.py"
click node_worker "https://github.com/arc53/docsgpt/blob/main/docsgpt/worker.py"
click node_db "https://github.com/arc53/docsgpt/blob/main/docsgpt/storage/db/session.py"
click node_vectors "https://github.com/arc53/docsgpt/blob/main/docsgpt/vectorstore/vector_creator.py"
click node_files "https://github.com/arc53/docsgpt/blob/main/docsgpt/storage/storage_creator.py"
click node_auth "https://github.com/arc53/docsgpt/blob/main/docsgpt/api/user/resource_access.py"
click node_teams "https://github.com/arc53/docsgpt/blob/main/docsgpt/api/admin/quotas.py"
click node_schedules "https://github.com/arc53/docsgpt/blob/main/docsgpt/api/user/schedules/routes.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_web,node_widget,node_api,node_answer,node_v1,node_mcp,node_user toneBlue
class node_search,node_retriever,node_ingest,node_connectors,node_worker toneAmber
class node_agent,node_workflow,node_guard,node_tools,node_models toneMint
class node_db,node_vectors,node_files toneRose
class node_auth,node_teams,node_schedules toneIndigo
```

## Components

### User experience

- [Web app](https://github.com/arc53/docsgpt/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Chat widget](https://github.com/arc53/docsgpt/blob/main/extensions/react-widget/src/App.tsx): `extensions/react-widget/src/App.tsx`
- [API routes](https://github.com/arc53/docsgpt/blob/main/docsgpt/app.py): `docsgpt/app.py`
- [Answer endpoint](https://github.com/arc53/docsgpt/blob/main/docsgpt/api/answer/routes/answer.py): `docsgpt/api/answer/routes/answer.py`
- [OpenAI API](https://github.com/arc53/docsgpt/blob/main/docsgpt/api/v1/routes.py): `docsgpt/api/v1/routes.py`
- [MCP server](https://github.com/arc53/docsgpt/blob/main/docsgpt/mcp_server.py): `docsgpt/mcp_server.py`

### Knowledge pipeline

- [Search service](https://github.com/arc53/docsgpt/blob/main/docsgpt/services/search_service.py): `docsgpt/services/search_service.py`
- [Retrieval strategies](https://github.com/arc53/docsgpt/blob/main/docsgpt/retriever/dispatcher.py): `docsgpt/retriever/dispatcher.py`
- [Document ingestion](https://github.com/arc53/docsgpt/blob/main/docsgpt/parser/embedding_pipeline.py): `docsgpt/parser/embedding_pipeline.py`
- [Knowledge connectors](https://github.com/arc53/docsgpt/blob/main/docsgpt/connectors/service.py): `docsgpt/connectors/service.py`
- [Background worker](https://github.com/arc53/docsgpt/blob/main/docsgpt/worker.py): `docsgpt/worker.py`

### Agent runtime

- [Agent execution](https://github.com/arc53/docsgpt/blob/main/docsgpt/agents/agentic_agent.py): `docsgpt/agents/agentic_agent.py`
- [Workflow engine](https://github.com/arc53/docsgpt/blob/main/docsgpt/agents/workflows/workflow_engine.py): `docsgpt/agents/workflows/workflow_engine.py`
- [Guardrails](https://github.com/arc53/docsgpt/blob/main/docsgpt/guardrails/engine.py): `docsgpt/guardrails/engine.py`
- [Agent tools](https://github.com/arc53/docsgpt/blob/main/docsgpt/agents/default_tools.py): `docsgpt/agents/default_tools.py`
- [Model providers](https://github.com/arc53/docsgpt/blob/main/docsgpt/llm/llm_creator.py): `docsgpt/llm/llm_creator.py`

### Platform services

- [Postgres data](https://github.com/arc53/docsgpt/blob/main/docsgpt/storage/db/session.py): `docsgpt/storage/db/session.py`
- [Vector stores](https://github.com/arc53/docsgpt/blob/main/docsgpt/vectorstore/vector_creator.py): `docsgpt/vectorstore/vector_creator.py`
- [File storage](https://github.com/arc53/docsgpt/blob/main/docsgpt/storage/storage_creator.py): `docsgpt/storage/storage_creator.py`

### Administration

- [Identity and access](https://github.com/arc53/docsgpt/blob/main/docsgpt/api/user/resource_access.py): `docsgpt/api/user/resource_access.py`
- [Teams and quotas](https://github.com/arc53/docsgpt/blob/main/docsgpt/api/admin/quotas.py): `docsgpt/api/admin/quotas.py`
- [Schedules and webhooks](https://github.com/arc53/docsgpt/blob/main/docsgpt/api/user/schedules/routes.py): `docsgpt/api/user/schedules/routes.py`

### Other components

- **User or client**

## Connections

- User or client → Web app: uses (evidence: `README.md`)
- User or client → Chat widget: uses (evidence: `README.md`)
- User or client → API routes: requests (evidence: `README.md`)
- User or client → MCP server: queries (evidence: `README.md`)
- Web app → API routes: calls (evidence: `README.md`)
- Chat widget → API routes: calls (evidence: `README.md`)
- API routes → Answer endpoint: routes
- API routes → OpenAI API: routes (evidence: `docsgpt/app.py`)
- Answer endpoint → Agent execution: runs
- OpenAI API → Agent execution: runs (evidence: `docsgpt/api/v1/routes.py`)
- MCP server → Search service: searches
- Agent execution → Search service: retrieves
- Search service → Retrieval strategies: dispatches (evidence: `docsgpt/services/search_service.py`)
- Retrieval strategies → Vector stores: queries
- Agent execution → Model providers: invokes
- Agent execution → Agent tools: executes
- Agent execution → Guardrails: checks
- Background worker → Document ingestion: runs
- Knowledge connectors → Document ingestion: syncs content
- Document ingestion → Vector stores: indexes (evidence: `docsgpt/parser/embedding_pipeline.py`)
- Document ingestion → Postgres data: records progress (evidence: `docsgpt/parser/embedding_pipeline.py`)
- Background worker → Postgres data: uses (evidence: `README.md`)
- Background worker → Vector stores: uses (evidence: `README.md`)
- Background worker → File storage: uses (evidence: `README.md`)
- API routes → Postgres data: uses (evidence: `README.md`)
- API routes → Vector stores: uses (evidence: `README.md`)
- API routes → File storage: uses (evidence: `README.md`)
- Workflow engine → Agent execution: runs nodes (evidence: `docsgpt/agents/workflows/workflow_engine.py`)
- Workflow engine → Agent tools: uses
- API routes → Identity and access: checks access
- API routes → Teams and quotas: administers
- API routes → Schedules and webhooks: manages
