Introduction

DocsGPT combines a web application, an agent runtime, and a document retrieval pipeline. An agent can answer from indexed sources, decide when to search, call tools, or execute a workflow. The same backend serves the web UI, embedded widgets, and API clients.

This page describes the components and their execution boundaries. For installation commands, use the development, package, Docker, or Kubernetes guide.

High-level architecture

The API and Celery workers are separate processes that reuse the same agent, model, parser, retrieval, and storage modules. Redis carries queued work between them; both processes need access to the configured storage and model services.

The storage boxes describe responsibilities, not a required number of servers. FAISS runs in-process and persists index files through local or S3 storage; pgvector can share a PostgreSQL server with application data. Dashed connections represent optional tool integrations. Redis also handles caching and live event delivery, which the task arrows omit.

Component responsibilities

API entry points

The ASGI application  mounts Flask through a WSGI adapter, the FastMCP server, and native asynchronous routes in one process. The asynchronous routes are the ones that hold a response open: the notification stream, chat reconnect, the remote-device command stream, and artifact downloads. They run on the event loop, so an idle connection doesn’t occupy a Flask worker thread.

DocsGPT also acts as an MCP client: agents can call external MCP servers through the MCP tool integration. This is a separate direction from exposing DocsGPT search at /mcp.

Agents and retrieval

The agent types control how a request gathers information and performs work:

• Classic retrieves configured source context before answering and can use configured tools.
• Agentic gives the model an internal_search tool so it can search as needed, refine a query, or answer without retrieval.
• Research coordinates clarification, planning, research, and synthesis with execution budgets.
• Workflow executes a graph of nodes with shared state and branching. See Workflow Nodes.

Per-source configuration can mix context retrieved before generation and sources exposed through the search tool. The retrieval dispatcher groups sources by retriever and merges results under a shared token budget. Optional query rephrasing happens before retrieval; relevance pre-screening happens afterward.

The retrieval paths are classic vector similarity, hybrid vector/keyword search, and GraphRAG. GraphRAG requires GRAPHRAG_ENABLED=true and VECTOR_STORE=pgvector; its graph tables live alongside the vectors. Sources without a ready graph can fall back to classic retrieval.

Model adapters keep agent logic independent of the provider. See Cloud Providers, Local Inference, and Embeddings for supported options. Prompt assembly and context compression determine what context reaches the model.

Answer lifecycle

This sequence shows an interactive streaming request. Retrieval and tool calls are optional and can repeat; a workflow can compose several such steps.

Interactive generation runs in the API process. A client disconnect can be followed by replay and a live tail while generation continues; this does not restart generation after an API process crash. Reconnect can happen during generation, not only after the final message shown above.

For persisted chat, Postgres holds the message_events journal and Redis pub/sub carries live events. User notifications use a separate Redis Stream backlog. See Real-time Events for replay cursors, retention, and connection limits.

When a tool requires approval, interactive execution pauses and stores continuation state; the client can submit the decision to resume. Background webhook and scheduled runs execute through Celery using the shared agent runtime. Their tool policies differ where no interactive approval is available.

Document lifecycle

Source ingestion builds reusable retrieval indexes. This diagram follows an uploaded source. Chat attachments and files read by tools follow related parsing paths but do not automatically become indexed knowledge sources.

Connectors enqueue source identifiers and configuration; workers fetch the remote content before parsing. Progress events are also emitted during parsing and indexing, before the completion event shown above.

The default parser engine is anydoc. Docling is an optional parser engine, and OCR is configured separately. Parsing, chunking, and retrieval settings belong to the source; see Per-Source Configuration and OCR. Ingestion tracks chunk progress so retries can resume interrupted embedding/indexing work.

For GraphRAG sources, graph extraction is a separate queued step after indexing. Retrieval can use the vector index while the graph is being built.

Worker queues and embeddings

Celery routing  separates three queues by default:

A worker started without -Q consumes all configured queues. Separate workers can isolate expensive parsing and ingestion from query embedding; three queues do not require three worker processes.

Inside a worker task, the embedding adapter runs directly instead of submitting another embedding task to itself. Indexing and querying must use consistent embedding configuration. Changing the embedding model requires rebuilding the affected embeddings; see Embeddings.

Storage and access boundaries

MongoDB is optional for Mongo Atlas Vector Search or a legacy user-data migration; it is not required for the default installation.

Authentication and resource authorization happen at API boundaries. OIDC SSO, roles and team grants, and agent API keys serve different access paths. Authentication defaults to local no-auth mode; SSO and persisted roles require configuration. Tool approvals and configured guardrails provide additional checks during agent execution.

Tool execution can cross another process or machine boundary. Artifacts and code execution use an optional sandbox runner. Remote Device executes on a paired machine running docsgpt-cli host, which connects outward to DocsGPT. External MCP servers provide their own tool execution environment.

Deployment architecture

A typical installation needs an API process, a Celery worker, Postgres, Redis, persistent file/index storage, and access to its configured models. Add a scheduler for scheduled runs and periodic jobs. A GPU, external vector database, separate frontend server, and sandbox are configuration choices.

When splitting services across machines, plan access to file storage and indexes as well as databases. With local storage, the API and workers need consistent shared paths. S3 can hold source and FAISS index files, but FAISS still executes inside the calling process. Models and enabled tool services must be reachable from the process using them.

Ingestion workers also call back to the API to register sources and indexes. Configure a reachable API_URL and a matching INTERNAL_KEY on the API and workers.

Serve the ASGI application behind a proxy configured for SSE. Keep the scheduler topology deliberate when scaling workers, and run schema migrations as part of deployment. See App Configuration and Observability.

Related Arc53 projects

These open-source projects connect through the API, provide optional tool execution, or supply libraries used inside the backend. They do not all need to be deployed together.

The Python package’s docsgpt api and docsgpt worker commands operate the server. The separate docsgpt-cli project is a client and optional device host. Any bot-specific conversation mapping or database belongs to that integration, not to DocsGPT’s default server requirements.

Code map

The main extension points in arc53/DocsGPT  are: