# sup3rus3r/obsidian-ai architecture

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

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

## Overview

Obsidian AI is a self-hosted visual control plane for configuring and running agents, teams, and workflows. The main user path is configuring an agent in the playground, sending a chat request, executing it through an LLM provider (with optional tools and knowledge retrieval), and retaining session history. Separate product branches cover workflow automation, evaluations, observability, authentication, and WhatsApp. The README documents these capabilities; sampled source confirms portions of chat-adjacent services, RAG, sessions, evaluation, and WhatsApp, so uncertain internal wiring is left out.

Main entry points: [`backend/services/agent_runner.py`](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/services/agent_runner.py) (Agent runner), [`backend/llm/provider_factory.py`](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/llm/provider_factory.py) (Provider factory), [`backend/routers/workflows_router.py`](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/routers/workflows_router.py) (Workflow API), [`frontend/app/(authenticated)/playground/page.tsx`](https://github.com/sup3rus3r/obsidian-ai/blob/main/frontend/app/(authenticated)/playground/page.tsx) (Playground)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_playground["Playground<br/>[page.tsx]"]
  node_api_client["API client<br/>[api-client.ts]"]
end

subgraph group_orchestration["Agent orchestration"]
  node_chat_api["Chat API<br/>[chat_router.py]"]
  node_agent_runner["Agent runner<br/>[agent_runner.py]"]
  node_workflow_api["Workflow API"]
  node_dag_executor["DAG executor<br/>[dag_executor.py]"]
  node_teams["Team delegation"]
end

subgraph group_capabilities["Agent capabilities"]
  node_tooling["Tools and MCP<br/>[builtin_tools.py]"]
  node_knowledge_api["Knowledge API"]
  node_rag["RAG service<br/>[rag_service.py]"]
  node_eval_api["Evaluation API<br/>[eval_router.py]"]
  node_eval_engine["Evaluation engine<br/>[eval_engine.py]"]
end

subgraph group_state["Data and operations"]
  node_session_api["Session history<br/>[sessions_router.py]"]
  node_database[("Database<br/>[database.py]")]
  node_file_storage[("File storage<br/>[file_storage.py]")]
  node_auth["Authentication<br/>[auth_router.py]"]
end

subgraph group_integrations["External integrations"]
  node_provider_factory["Provider factory"]
  node_llm_providers["LLM providers"]
  node_whatsapp_api["WhatsApp service"]
  node_wa_bridge["WhatsApp bridge<br/>[index.js]"]
end

node_user(("User"))
node_whatsapp(("WhatsApp"))

node_user -->|"configures and chats"| node_playground
node_playground -->|"sends requests"| node_api_client
node_api_client -->|"calls chat API"| node_chat_api
node_chat_api -->|"runs agent"| node_agent_runner
node_agent_runner -->|"creates provider"| node_provider_factory
node_provider_factory -->|"selects provider"| node_llm_providers
node_agent_runner -->|"uses tools"| node_tooling
node_knowledge_api -->|"indexes knowledge"| node_rag
node_eval_api -->|"runs evaluations"| node_eval_engine
node_eval_engine -->|"creates provider"| node_provider_factory
node_session_api -->|"reads and writes"| node_database
node_auth -->|"reads and writes"| node_database
node_whatsapp_api -->|"sends and receives"| node_wa_bridge
node_whatsapp -->|"exchanges messages"| node_wa_bridge
node_workflow_api -->|"executes workflow"| node_dag_executor
node_workflow_api -.->|"coordinates agents"| node_teams

click node_playground "https://github.com/sup3rus3r/obsidian-ai/blob/main/frontend/app/(authenticated)/playground/page.tsx"
click node_api_client "https://github.com/sup3rus3r/obsidian-ai/blob/main/frontend/lib/api-client.ts"
click node_chat_api "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/routers/chat_router.py"
click node_agent_runner "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/services/agent_runner.py"
click node_workflow_api "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/routers/workflows_router.py"
click node_dag_executor "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/dag_executor.py"
click node_teams "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/team_delegation_tools.py"
click node_provider_factory "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/llm/provider_factory.py"
click node_llm_providers "https://github.com/sup3rus3r/obsidian-ai/tree/main/backend/llm"
click node_tooling "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/builtin_tools.py"
click node_knowledge_api "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/routers/knowledge_router.py"
click node_rag "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/rag_service.py"
click node_eval_api "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/routers/eval_router.py"
click node_eval_engine "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/eval_engine.py"
click node_session_api "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/routers/sessions_router.py"
click node_database "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/database.py"
click node_file_storage "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/file_storage.py"
click node_auth "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/routers/auth_router.py"
click node_whatsapp_api "https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/services/whatsapp_service.py"
click node_wa_bridge "https://github.com/sup3rus3r/obsidian-ai/blob/main/wa-bridge/index.js"

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_playground,node_api_client,node_user toneBlue
class node_chat_api,node_agent_runner,node_workflow_api,node_dag_executor,node_teams toneAmber
class node_tooling,node_knowledge_api,node_rag,node_eval_api,node_eval_engine toneMint
class node_session_api,node_database,node_file_storage,node_auth toneRose
class node_provider_factory,node_llm_providers,node_whatsapp_api,node_wa_bridge,node_whatsapp toneIndigo
```

## Components

### User experience

- [Playground](https://github.com/sup3rus3r/obsidian-ai/blob/main/frontend/app/(authenticated)/playground/page.tsx): `frontend/app/(authenticated)/playground/page.tsx`
- [API client](https://github.com/sup3rus3r/obsidian-ai/blob/main/frontend/lib/api-client.ts): `frontend/lib/api-client.ts`

### Agent orchestration

- [Chat API](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/routers/chat_router.py): `backend/routers/chat_router.py`
- [Agent runner](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/services/agent_runner.py): `backend/services/agent_runner.py`
- [Workflow API](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/routers/workflows_router.py): `backend/routers/workflows_router.py`
- [DAG executor](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/dag_executor.py): `backend/dag_executor.py`
- [Team delegation](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/team_delegation_tools.py): `backend/team_delegation_tools.py`

### Agent capabilities

- [Tools and MCP](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/builtin_tools.py): `backend/builtin_tools.py`
- [Knowledge API](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/routers/knowledge_router.py): `backend/routers/knowledge_router.py`
- [RAG service](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/rag_service.py): `backend/rag_service.py`
- [Evaluation API](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/routers/eval_router.py): `backend/routers/eval_router.py`
- [Evaluation engine](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/eval_engine.py): `backend/eval_engine.py`

### Data and operations

- [Session history](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/routers/sessions_router.py): `backend/routers/sessions_router.py`
- [Database](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/database.py): `backend/database.py`
- [File storage](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/file_storage.py): `backend/file_storage.py`
- [Authentication](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/routers/auth_router.py): `backend/routers/auth_router.py`

### External integrations

- [Provider factory](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/llm/provider_factory.py): `backend/llm/provider_factory.py`
- [LLM providers](https://github.com/sup3rus3r/obsidian-ai/tree/main/backend/llm): `backend/llm`
- [WhatsApp service](https://github.com/sup3rus3r/obsidian-ai/blob/main/backend/services/whatsapp_service.py): `backend/services/whatsapp_service.py`
- [WhatsApp bridge](https://github.com/sup3rus3r/obsidian-ai/blob/main/wa-bridge/index.js): `wa-bridge/index.js`

### Other components

- **User**
- **WhatsApp**

## Connections

- User → Playground: configures and chats
- Playground → API client: sends requests
- API client → Chat API: calls chat API
- Chat API → Agent runner: runs agent
- Agent runner → Provider factory: creates provider
- Provider factory → LLM providers: selects provider
- Agent runner → Tools and MCP: uses tools
- Knowledge API → RAG service: indexes knowledge
- Evaluation API → Evaluation engine: runs evaluations
- Evaluation engine → Provider factory: creates provider
- Session history → Database: reads and writes
- Authentication → Database: reads and writes
- WhatsApp service → WhatsApp bridge: sends and receives
- WhatsApp → WhatsApp bridge: exchanges messages
- Workflow API → DAG executor: executes workflow
- Workflow API → Team delegation: coordinates agents