# cinnamon/kotaemon architecture

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

- Interactive diagram: https://gitdiagram.com/cinnamon/kotaemon
- Repository: https://github.com/cinnamon/kotaemon

## Overview

#### Purpose and entry points
Kotaemon is a Python 3.10+ document-question-answering platform: a Gradio RAG UI plus reusable `kotaemon` framework library. Runtime starts at `app.py`, which hosts the application assembled in `libs/ktem/ktem/main.py` and `libs/ktem/ktem/app.py`. `sso_app.py` is a separate SSO-oriented launch path. Deployment supports local scripts, Docker, and Fly.io (`Dockerfile`, `fly.toml`).

#### Two-layer architecture
- **Framework layer (`kotaemon`)** provides composable abstractions for components, schemas, LLMs, embeddings, loaders, indexing, retrieval, storage, and agents. Core contracts live in `libs/kotaemon/kotaemon/base/component.py` and `libs/kotaemon/kotaemon/base/schema.py`.
- **Application layer (`ktem`)** wires those capabilities into persistent configuration, user-facing resource management, indexing, reasoning pipelines, and Gradio pages. Its extension seam is `libs/ktem/ktem/extension_protocol.py`; app-wide customization is centered on `flowsettings.py`.

#### Application state, users, and managed resources
The application persists users, conversations, configured models, index metadata, and MCP configuration through its database layer: `libs/ktem/ktem/db/engine.py`, `libs/ktem/ktem/db/models.py`, and Alembic assets under `libs/ktem/migrations/`. Data defaults to `ktem_app_data` at runtime. Resource managers expose database-configured LLM, embedding, reranking, and MCP providers to UI and pipelines: `libs/ktem/ktem/llms/manager.py`, `libs/ktem/ktem/embeddings/manager.py`, `libs/ktem/ktem/mcp/manager.py`.

#### Document ingestion and indexing
File indexing begins with file-index orchestration in `libs/ktem/ktem/index/file/index.py` and pipelines in `libs/ktem/ktem/index/file/pipelines.py`. It delegates parsing/loading to pluggable loaders, including PDFs, Office documents, web sources, OCR, and multimodal services (`libs/kotaemon/kotaemon/loaders/pdf_loader.py`, `libs/kotaemon/kotaemon/loaders/docling_loader.py`, `libs/kotaemon/kotaemon/loaders/azureai_document_intelligence_loader.py`). Parsed documents are split, embedded, and written through the vector-index abstraction (`libs/kotaemon/kotaemon/indices/vectorindex.py`) into selected document/vector stores.

#### Retrieval and persistence boundary
The standard RAG path combines document/full-text and vector retrieval, optionally reranks results, then formats context and citations before generation. Storage adapters isolate backing services: document stores support Elasticsearch, LanceDB, file, and memory (`libs/kotaemon/kotaemon/storages/docstores/elasticsearch.py`, `libs/kotaemon/kotaemon/storages/docstores/lancedb.py`); vector stores support Chroma, LanceDB, Milvus, Qdrant, file, and memory (`libs/kotaemon/kotaemon/storages/vectorstores/qdrant.py`, `libs/kotaemon/kotaemon/storages/vectorstores/chroma.py`). Citation QA is implemented in `libs/kotaemon/kotaemon/indices/qa/citation_qa.py`.

#### Reasoning and generation
UI-selected reasoning pipelines control query execution: basic and decomposition QA, ReAct, and ReWOO reside in `libs/ktem/ktem/reasoning/simple.py`, `libs/ktem/ktem/reasoning/react.py`, and `libs/ktem/ktem/reasoning/rewoo.py`. Agent implementations can invoke LLM, Google, Wikipedia, or MCP tools (`libs/kotaemon/kotaemon/agents/react/agent.py`, `libs/kotaemon/kotaemon/agents/tools/mcp.py`). Model adapters isolate OpenAI-compatible endpoints, LangChain-backed models, and local llama.cpp (`libs/kotaemon/kotaemon/llms/chats/openai.py`, `libs/kotaemon/kotaemon/llms/chats/llamacpp.py`).

#### UI and advanced index modes
Gradio pages provide chat, login, setup, resources, and settings; chat composition is concentrated in `libs/ktem/ktem/pages/chat/chat_panel.py`, while resource and settings flows are in `libs/ktem/ktem/pages/settings.py`. File indexing can switch to GraphRAG-family strategies—native graph, LightRAG, NanoGraphRAG, or KNet—behind dedicated pipelines (`libs/ktem/ktem/index/file/graph/graph_index.py`, `libs/ktem/ktem/index/file/graph/lightrag_pipelines.py`, `libs/ktem/ktem/index/file/knet/knet_index.py`). Optional external services include OpenAI/Azure OpenAI, Ollama, Cohere, VoyageAI, Adobe, Azure Document Intelligence, and MCP servers.

Main entry points: [`libs/ktem/ktem/main.py`](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/main.py) (App assembly), [`libs/ktem/ktem/pages/chat/chat_panel.py`](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/pages/chat/chat_panel.py) (Chat UI), [`libs/ktem/ktem/app.py`](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/app.py) (Gradio application), [`libs/ktem/ktem/llms/manager.py`](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/llms/manager.py) (Resource managers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime &amp; UI"]
  node_launch["Application launch<br/>Python entry point<br/>[app.py]"]
  node_sso_launch["SSO launch<br/>Python entry point<br/>[sso_app.py]"]
  node_chat_ui["Chat UI<br/>Gradio page<br/>[chat_panel.py]"]
  node_settings_ui["Resources &amp; settings<br/>Gradio pages<br/>[settings.py]"]
end

subgraph group_app["ktem Application"]
  node_app_assembly["App assembly<br/>application bootstrap<br/>[main.py]"]
  node_app_shell["Gradio application<br/>UI host<br/>[app.py]"]
  node_extensions{{"Extension protocol<br/>customization seam"}}
  node_resource_managers["Resource managers<br/>provider registry<br/>[manager.py]"]
  node_file_indexing["File indexing<br/>ingestion orchestrator<br/>[index.py]"]
  node_index_pipelines["Index pipelines<br/>ingestion pipelines<br/>[pipelines.py]"]
  node_graph_indexing["Graph index modes<br/>GraphRAG pipelines<br/>[graph_index.py]"]
  node_reasoning["Reasoning pipelines<br/>QA orchestration<br/>[simple.py]"]
end

subgraph group_framework["kotaemon Framework"]
  node_core_contracts{{"Core contracts<br/>component and schema APIs<br/>[component.py]"}}
  node_loaders["Document loaders<br/>pluggable parsers<br/>[pdf_loader.py]"]
  node_vector_index["Vector index<br/>index abstraction<br/>[vectorindex.py]"]
  node_retrieval_qa["Citation QA<br/>RAG retrieval and generation<br/>[citation_qa.py]"]
  node_agents["Tool agents<br/>ReAct agent<br/>[agent.py]"]
  node_llm_adapters["LLM adapters<br/>model integrations<br/>[openai.py]"]
end

subgraph group_persistence["Persistence"]
  node_database[("App database<br/>SQL persistence<br/>[engine.py]")]
  node_db_models["Database models<br/>ORM models<br/>[models.py]"]
  node_storage_adapters[("Document &amp; vector stores<br/>storage adapters<br/>[qdrant.py]")]
end

node_launch -->|"starts"| node_app_assembly
node_sso_launch -->|"starts"| node_app_assembly
node_app_assembly -->|"builds"| node_app_shell
node_app_shell -->|"hosts"| node_chat_ui
node_app_shell -->|"hosts"| node_settings_ui
node_app_assembly -.->|"customizes via"| node_extensions
node_settings_ui -->|"configures"| node_resource_managers
node_resource_managers -->|"loads configuration"| node_database
node_database -->|"uses"| node_db_models
node_chat_ui -->|"selects"| node_reasoning
node_chat_ui -->|"submits files"| node_file_indexing
node_file_indexing -->|"runs"| node_index_pipelines
node_index_pipelines -->|"parses with"| node_loaders
node_index_pipelines -->|"indexes"| node_vector_index
node_file_indexing -.->|"can switch to"| node_graph_indexing
node_vector_index -->|"writes to"| node_storage_adapters
node_reasoning -->|"executes RAG"| node_retrieval_qa
node_reasoning -.->|"uses for tool flows"| node_agents
node_retrieval_qa -->|"retrieves from"| node_storage_adapters
node_retrieval_qa -->|"generates with"| node_llm_adapters
node_agents -->|"calls"| node_llm_adapters
node_resource_managers -->|"provisions"| node_llm_adapters
node_loaders -.->|"implements"| node_core_contracts
node_vector_index -.->|"implements"| node_core_contracts

click node_launch "https://github.com/cinnamon/kotaemon/blob/main/app.py"
click node_sso_launch "https://github.com/cinnamon/kotaemon/blob/main/sso_app.py"
click node_app_assembly "https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/main.py"
click node_app_shell "https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/app.py"
click node_chat_ui "https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/pages/chat/chat_panel.py"
click node_settings_ui "https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/pages/settings.py"
click node_extensions "https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/extension_protocol.py"
click node_database "https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/db/engine.py"
click node_db_models "https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/db/models.py"
click node_resource_managers "https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/llms/manager.py"
click node_file_indexing "https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/index/file/index.py"
click node_index_pipelines "https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/index/file/pipelines.py"
click node_graph_indexing "https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/index/file/graph/graph_index.py"
click node_reasoning "https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/reasoning/simple.py"
click node_core_contracts "https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/base/component.py"
click node_loaders "https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/pdf_loader.py"
click node_vector_index "https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/indices/vectorindex.py"
click node_retrieval_qa "https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/indices/qa/citation_qa.py"
click node_agents "https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/react/agent.py"
click node_llm_adapters "https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/llms/chats/openai.py"
click node_storage_adapters "https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/storages/vectorstores/qdrant.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_launch,node_sso_launch,node_chat_ui,node_settings_ui toneBlue
class node_app_assembly,node_app_shell,node_extensions,node_resource_managers,node_file_indexing,node_index_pipelines,node_graph_indexing,node_reasoning toneAmber
class node_core_contracts,node_loaders,node_vector_index,node_retrieval_qa,node_agents,node_llm_adapters toneMint
class node_database,node_db_models,node_storage_adapters toneRose
```

## Components

### Runtime & UI

- [Application launch](https://github.com/cinnamon/kotaemon/blob/main/app.py): Python entry point · `app.py`
- [SSO launch](https://github.com/cinnamon/kotaemon/blob/main/sso_app.py): Python entry point · `sso_app.py`
- [Chat UI](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/pages/chat/chat_panel.py): Gradio page · `libs/ktem/ktem/pages/chat/chat_panel.py`
- [Resources & settings](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/pages/settings.py): Gradio pages · `libs/ktem/ktem/pages/settings.py`

### ktem Application

- [App assembly](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/main.py): application bootstrap · `libs/ktem/ktem/main.py`
- [Gradio application](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/app.py): UI host · `libs/ktem/ktem/app.py`
- [Extension protocol](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/extension_protocol.py): customization seam · `libs/ktem/ktem/extension_protocol.py`
- [Resource managers](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/llms/manager.py): provider registry · Exposes database-configured LLM, embedding, reranking, and MCP providers. · `libs/ktem/ktem/llms/manager.py`
- [File indexing](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/index/file/index.py): ingestion orchestrator · `libs/ktem/ktem/index/file/index.py`
- [Index pipelines](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/index/file/pipelines.py): ingestion pipelines · `libs/ktem/ktem/index/file/pipelines.py`
- [Graph index modes](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/index/file/graph/graph_index.py): GraphRAG pipelines · Supports native graph, LightRAG, NanoGraphRAG, and KNet modes. · `libs/ktem/ktem/index/file/graph/graph_index.py`
- [Reasoning pipelines](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/reasoning/simple.py): QA orchestration · Selects basic, decomposition, ReAct, or ReWOO execution. · `libs/ktem/ktem/reasoning/simple.py`

### kotaemon Framework

- [Core contracts](https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/base/component.py): component and schema APIs · `libs/kotaemon/kotaemon/base/component.py`
- [Document loaders](https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/loaders/pdf_loader.py): pluggable parsers · Handles PDF, Office, web, OCR, and multimodal sources. · `libs/kotaemon/kotaemon/loaders/pdf_loader.py`
- [Vector index](https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/indices/vectorindex.py): index abstraction · Splits, embeds, and writes parsed documents. · `libs/kotaemon/kotaemon/indices/vectorindex.py`
- [Citation QA](https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/indices/qa/citation_qa.py): RAG retrieval and generation · Combines retrieval, reranking, context formatting, citations, and generation. · `libs/kotaemon/kotaemon/indices/qa/citation_qa.py`
- [Tool agents](https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/agents/react/agent.py): ReAct agent · Can call LLM, web, Wikipedia, and MCP tools. · `libs/kotaemon/kotaemon/agents/react/agent.py`
- [LLM adapters](https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/llms/chats/openai.py): model integrations · Supports OpenAI-compatible, LangChain, and llama.cpp models. · `libs/kotaemon/kotaemon/llms/chats/openai.py`

### Persistence

- [App database](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/db/engine.py): SQL persistence · Persists users, conversations, configured resources, indexes, and MCP settings. · `libs/ktem/ktem/db/engine.py`
- [Database models](https://github.com/cinnamon/kotaemon/blob/main/libs/ktem/ktem/db/models.py): ORM models · `libs/ktem/ktem/db/models.py`
- [Document & vector stores](https://github.com/cinnamon/kotaemon/blob/main/libs/kotaemon/kotaemon/storages/vectorstores/qdrant.py): storage adapters · Isolates Elasticsearch, LanceDB, Chroma, Qdrant, file, memory, and Milvus backends. · `libs/kotaemon/kotaemon/storages/vectorstores/qdrant.py`

## Connections

- Application launch → App assembly: starts
- SSO launch → App assembly: starts
- App assembly → Gradio application: builds
- Gradio application → Chat UI: hosts
- Gradio application → Resources & settings: hosts
- App assembly → Extension protocol: customizes via
- Resources & settings → Resource managers: configures
- Resource managers → App database: loads configuration
- App database → Database models: uses
- Chat UI → Reasoning pipelines: selects
- Chat UI → File indexing: submits files
- File indexing → Index pipelines: runs
- Index pipelines → Document loaders: parses with
- Index pipelines → Vector index: indexes
- File indexing → Graph index modes: can switch to
- Vector index → Document & vector stores: writes to
- Reasoning pipelines → Citation QA: executes RAG
- Reasoning pipelines → Tool agents: uses for tool flows
- Citation QA → Document & vector stores: retrieves from
- Citation QA → LLM adapters: generates with
- Tool agents → LLM adapters: calls
- Resource managers → LLM adapters: provisions
- Document loaders → Core contracts: implements
- Vector index → Core contracts: implements
