# khoj-ai/khoj architecture

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

- Interactive diagram: https://gitdiagram.com/khoj-ai/khoj
- Repository: https://github.com/khoj-ai/khoj

## Overview

Khoj is a self-hostable personal AI application. Users enter through web, desktop, Obsidian, phone, or messaging clients to chat with models, search personal documents and the web, create agents, or schedule research automations. The backend exposes API capabilities, processes and indexes multiple content formats, retrieves relevant entries, and combines them with model/tool execution. The README documents the product branches; sampled source supports several internal links, while unsampled router wiring is left unverified.

Main entry points: [`src/khoj/main.py`](https://github.com/khoj-ai/khoj/blob/master/src/khoj/main.py) (Application server), [`src/khoj/search_type/text_search.py`](https://github.com/khoj-ai/khoj/blob/master/src/khoj/search_type/text_search.py) (Text search), [`src/khoj/routers/research.py`](https://github.com/khoj-ai/khoj/blob/master/src/khoj/routers/research.py) (Research orchestration), [`src/khoj/routers/api_chat.py`](https://github.com/khoj-ai/khoj/blob/master/src/khoj/routers/api_chat.py) (Chat endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Interfaces"]
  node_web["Web app"]
  node_desktop["Desktop app<br/>[main.js]"]
  node_obsidian["Obsidian plugin<br/>[main.ts]"]
  node_android["Android app"]
end

subgraph group_api["API Services"]
  node_server["Application server<br/>[main.py]"]
  node_chatapi["Chat endpoints<br/>[api_chat.py]"]
  node_agentsapi["Agent endpoints<br/>[api_agents.py]"]
  node_automationapi["Automation endpoints<br/>[api_automation.py]"]
  node_research["Research orchestration<br/>[research.py]"]
  node_contentapi["Content endpoints<br/>[api_content.py]"]
end

subgraph group_knowledge["Knowledge Retrieval"]
  node_ingestion["Content extraction"]
  node_search["Text search<br/>[text_search.py]"]
  node_filters["Search filters"]
  node_embeddings["Embedding models<br/>[embeddings.py]"]
end

subgraph group_ai["AI Capabilities"]
  node_conversation["Conversation models"]
  node_online["Online search<br/>[online_search.py]"]
  node_operator["Agent tools"]
  node_image["Image generation<br/>[generate.py]"]
  node_speech["Speech output<br/>[text_to_speech.py]"]
end

subgraph group_data["Application Data"]
  node_adapters["Data adapters<br/>[__init__.py]"]
  node_models[("Database models<br/>[__init__.py]")]
  node_state["Runtime state<br/>[state.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_user -->|"uses"| node_desktop
node_user -->|"uses"| node_obsidian
node_user -->|"uses"| node_android
node_web -.->|"API requests"| node_server
node_desktop -.->|"API requests"| node_server
node_obsidian -.->|"API requests"| node_server
node_android -.->|"API requests"| node_server
node_server -.->|"dispatches"| node_chatapi
node_server -.->|"dispatches"| node_agentsapi
node_server -.->|"dispatches"| node_automationapi
node_server -.->|"dispatches"| node_contentapi
node_chatapi -.->|"uses"| node_conversation
node_contentapi -.->|"processes content"| node_ingestion
node_ingestion -.->|"creates entries"| node_search
node_search -->|"queries"| node_adapters
node_search -->|"loads models"| node_models
node_search -->|"invokes setup"| node_ingestion
node_search -->|"reads runtime state"| node_state
node_embeddings -->|"uses models"| node_models
node_embeddings -->|"uses state"| node_state
node_research -->|"invokes tool"| node_online
node_research -->|"uses agents"| node_operator
node_research -->|"queries data"| node_models
node_research -->|"uses prompts"| node_conversation
node_adapters -->|"persists records"| node_models
node_server -->|"configures"| node_state
node_server -->|"initializes data"| node_adapters
node_agentsapi -.->|"configures agents"| node_operator
node_chatapi -.->|"supports generation"| node_image
node_chatapi -.->|"supports speech"| node_speech
node_search -.->|"applies filters"| node_filters
node_automationapi -.->|"schedules research"| node_research

click node_web "https://github.com/khoj-ai/khoj/tree/master/src/interface/web/app"
click node_desktop "https://github.com/khoj-ai/khoj/blob/master/src/interface/desktop/main.js"
click node_obsidian "https://github.com/khoj-ai/khoj/blob/master/src/interface/obsidian/src/main.ts"
click node_android "https://github.com/khoj-ai/khoj/blob/master/src/interface/android/app/src/main/java/dev/khoj/app/LauncherActivity.java"
click node_server "https://github.com/khoj-ai/khoj/blob/master/src/khoj/main.py"
click node_chatapi "https://github.com/khoj-ai/khoj/blob/master/src/khoj/routers/api_chat.py"
click node_agentsapi "https://github.com/khoj-ai/khoj/blob/master/src/khoj/routers/api_agents.py"
click node_automationapi "https://github.com/khoj-ai/khoj/blob/master/src/khoj/routers/api_automation.py"
click node_research "https://github.com/khoj-ai/khoj/blob/master/src/khoj/routers/research.py"
click node_contentapi "https://github.com/khoj-ai/khoj/blob/master/src/khoj/routers/api_content.py"
click node_ingestion "https://github.com/khoj-ai/khoj/tree/master/src/khoj/processor/content"
click node_search "https://github.com/khoj-ai/khoj/blob/master/src/khoj/search_type/text_search.py"
click node_filters "https://github.com/khoj-ai/khoj/tree/master/src/khoj/search_filter"
click node_embeddings "https://github.com/khoj-ai/khoj/blob/master/src/khoj/processor/embeddings.py"
click node_conversation "https://github.com/khoj-ai/khoj/tree/master/src/khoj/processor/conversation"
click node_online "https://github.com/khoj-ai/khoj/blob/master/src/khoj/processor/tools/online_search.py"
click node_operator "https://github.com/khoj-ai/khoj/tree/master/src/khoj/processor/operator"
click node_image "https://github.com/khoj-ai/khoj/blob/master/src/khoj/processor/image/generate.py"
click node_speech "https://github.com/khoj-ai/khoj/blob/master/src/khoj/processor/speech/text_to_speech.py"
click node_adapters "https://github.com/khoj-ai/khoj/blob/master/src/khoj/database/adapters/__init__.py"
click node_models "https://github.com/khoj-ai/khoj/blob/master/src/khoj/database/models/__init__.py"
click node_state "https://github.com/khoj-ai/khoj/blob/master/src/khoj/utils/state.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_desktop,node_obsidian,node_android,node_user toneBlue
class node_server,node_chatapi,node_agentsapi,node_automationapi,node_research,node_contentapi toneAmber
class node_ingestion,node_search,node_filters,node_embeddings toneMint
class node_conversation,node_online,node_operator,node_image,node_speech toneRose
class node_adapters,node_models,node_state toneIndigo
```

## Components

### User Interfaces

- [Web app](https://github.com/khoj-ai/khoj/tree/master/src/interface/web/app): `src/interface/web/app`
- [Desktop app](https://github.com/khoj-ai/khoj/blob/master/src/interface/desktop/main.js): `src/interface/desktop/main.js`
- [Obsidian plugin](https://github.com/khoj-ai/khoj/blob/master/src/interface/obsidian/src/main.ts): `src/interface/obsidian/src/main.ts`
- [Android app](https://github.com/khoj-ai/khoj/blob/master/src/interface/android/app/src/main/java/dev/khoj/app/LauncherActivity.java): `src/interface/android/app/src/main/java/dev/khoj/app/LauncherActivity.java`

### API Services

- [Application server](https://github.com/khoj-ai/khoj/blob/master/src/khoj/main.py): `src/khoj/main.py`
- [Chat endpoints](https://github.com/khoj-ai/khoj/blob/master/src/khoj/routers/api_chat.py): `src/khoj/routers/api_chat.py`
- [Agent endpoints](https://github.com/khoj-ai/khoj/blob/master/src/khoj/routers/api_agents.py): `src/khoj/routers/api_agents.py`
- [Automation endpoints](https://github.com/khoj-ai/khoj/blob/master/src/khoj/routers/api_automation.py): `src/khoj/routers/api_automation.py`
- [Research orchestration](https://github.com/khoj-ai/khoj/blob/master/src/khoj/routers/research.py): `src/khoj/routers/research.py`
- [Content endpoints](https://github.com/khoj-ai/khoj/blob/master/src/khoj/routers/api_content.py): `src/khoj/routers/api_content.py`

### Knowledge Retrieval

- [Content extraction](https://github.com/khoj-ai/khoj/tree/master/src/khoj/processor/content): `src/khoj/processor/content`
- [Text search](https://github.com/khoj-ai/khoj/blob/master/src/khoj/search_type/text_search.py): `src/khoj/search_type/text_search.py`
- [Search filters](https://github.com/khoj-ai/khoj/tree/master/src/khoj/search_filter): `src/khoj/search_filter`
- [Embedding models](https://github.com/khoj-ai/khoj/blob/master/src/khoj/processor/embeddings.py): `src/khoj/processor/embeddings.py`

### AI Capabilities

- [Conversation models](https://github.com/khoj-ai/khoj/tree/master/src/khoj/processor/conversation): `src/khoj/processor/conversation`
- [Online search](https://github.com/khoj-ai/khoj/blob/master/src/khoj/processor/tools/online_search.py): `src/khoj/processor/tools/online_search.py`
- [Agent tools](https://github.com/khoj-ai/khoj/tree/master/src/khoj/processor/operator): `src/khoj/processor/operator`
- [Image generation](https://github.com/khoj-ai/khoj/blob/master/src/khoj/processor/image/generate.py): `src/khoj/processor/image/generate.py`
- [Speech output](https://github.com/khoj-ai/khoj/blob/master/src/khoj/processor/speech/text_to_speech.py): `src/khoj/processor/speech/text_to_speech.py`

### Application Data

- [Data adapters](https://github.com/khoj-ai/khoj/blob/master/src/khoj/database/adapters/__init__.py): `src/khoj/database/adapters/__init__.py`
- [Database models](https://github.com/khoj-ai/khoj/blob/master/src/khoj/database/models/__init__.py): `src/khoj/database/models/__init__.py`
- [Runtime state](https://github.com/khoj-ai/khoj/blob/master/src/khoj/utils/state.py): `src/khoj/utils/state.py`

### Other components

- **User**

## Connections

- User → Web app: uses (evidence: `README.md`)
- User → Desktop app: uses (evidence: `README.md`)
- User → Obsidian plugin: uses (evidence: `README.md`)
- User → Android app: uses (evidence: `README.md`)
- Web app → Application server: API requests
- Desktop app → Application server: API requests
- Obsidian plugin → Application server: API requests
- Android app → Application server: API requests
- Application server → Chat endpoints: dispatches
- Application server → Agent endpoints: dispatches
- Application server → Automation endpoints: dispatches
- Application server → Content endpoints: dispatches
- Chat endpoints → Conversation models: uses
- Content endpoints → Content extraction: processes content
- Content extraction → Text search: creates entries (evidence: `src/khoj/search_type/text_search.py`)
- Text search → Data adapters: queries (evidence: `src/khoj/search_type/text_search.py`)
- Text search → Database models: loads models (evidence: `src/khoj/search_type/text_search.py`)
- Text search → Content extraction: invokes setup (evidence: `src/khoj/search_type/text_search.py`)
- Text search → Runtime state: reads runtime state (evidence: `src/khoj/search_type/text_search.py`)
- Embedding models → Database models: uses models (evidence: `src/khoj/processor/embeddings.py`)
- Embedding models → Runtime state: uses state (evidence: `src/khoj/utils/state.py`)
- Research orchestration → Online search: invokes tool (evidence: `src/khoj/routers/research.py`)
- Research orchestration → Agent tools: uses agents (evidence: `src/khoj/routers/research.py`)
- Research orchestration → Database models: queries data (evidence: `src/khoj/routers/research.py`)
- Research orchestration → Conversation models: uses prompts (evidence: `src/khoj/routers/research.py`)
- Data adapters → Database models: persists records (evidence: `src/khoj/database/adapters/__init__.py`)
- Application server → Runtime state: configures (evidence: `src/khoj/main.py`)
- Application server → Data adapters: initializes data (evidence: `src/khoj/main.py`)
- Agent endpoints → Agent tools: configures agents
- Chat endpoints → Image generation: supports generation
- Chat endpoints → Speech output: supports speech
- Text search → Search filters: applies filters
- Automation endpoints → Research orchestration: schedules research
