# logancyang/obsidian-copilot architecture

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

- Interactive diagram: https://gitdiagram.com/logancyang/obsidian-copilot
- Repository: https://github.com/logancyang/obsidian-copilot

## Overview

1. **Overall shape**
   - This is an **Obsidian community plugin** written in **TypeScript + React**.  
   - The plugin runs inside Obsidian’s desktop runtime and extends the editor with chat, command palette actions, vault QA/search, project mode, quick-ask, and agentic workflows.

2. **Top-level entry and plugin boundary**
   - `src/main.ts` is the plugin entrypoint. It wires together settings, managers, UI surfaces, commands, and lifecycle hooks.
   - The main architectural boundary is between **Obsidian-native APIs** on one side and the plugin’s own services/core/UI on the other.

3. **UI layer**
   - Most user-facing functionality lives under `src/components/**`.
   - `Chat.tsx`, `CopilotView.tsx`, `quick-ask/**`, and `composer/**` provide the primary interaction surfaces.
   - Chat UI is heavily decomposed: message rendering, input, context badges, tool-call banners, token warnings, and editor plugins are separated so the same state can drive multiple surfaces.

4. **Chat/session orchestration**
   - `src/core/ChatManager.ts`, `MessageRepository.ts`, `MessageLifecycle.ts`, and `ChatPersistenceManager.ts` manage conversation state, message persistence, and streaming updates.
   - `src/hooks/use-streaming-chat-session.ts` and `src/hooks/useChatManager.ts` connect UI events to the chat engine.
   - The flow is: user input/context → message lifecycle/state → selected chain runner/LLM provider → streamed output back to UI.

5. **LLM/provider abstraction**
   - `src/LLMProviders/**` contains adapters for multiple model backends: OpenAI-compatible providers, LM Studio, OpenRouter, Bedrock, GitHub Copilot, embeddings providers, and self-hosted services.
   - `chatModelManager.ts`, `embeddingManager.ts`, `modelAdapter.ts`, and `chainManager.ts` centralize provider selection and capability differences.
   - This layer is the key portability boundary: upstream features depend on a normalized model interface rather than hard-coding a single vendor.

6. **Chain runners and agent execution**
   - `src/LLMProviders/chainRunner/**` contains the execution strategies for different modes: standard chat, project QA, vault QA, copilot-plus, and autonomous agent flows.
   - These runners handle prompt construction, streaming parsing, tool-call detection, think/action blocks, citations, and finish-reason handling.
   - The agentic pipeline is: prompt/context assembly → model stream → parse tool calls / reasoning blocks → execute tools → append results → continue or finish.

7. **Tools subsystem**
   - `src/tools/**` defines the actionable capabilities exposed to the model and chat UI: search, note/file operations, tag/date utilities, YouTube, file tree, composer actions, memory, and Obsidian CLI-backed actions.
   - `ToolRegistry.ts`, `toolManager.ts`, and `createLangChainTool.ts` act as the dispatch layer.
   - Tools are a major boundary: the model never touches Obsidian state directly; it requests a tool, and the plugin mediates access to vault/editor/system operations.

8. **Context assembly and compaction**
   - `src/context/**`, `contextProcessor.ts`, and `context.ts` transform vault artifacts, mentions, selected text, embeds, and chat history into model-ready context blocks.
   - Compaction and layering logic (`ChatHistoryCompactor`, `L2ContextCompactor`, `LayerToMessagesConverter`) keep prompts within token limits while preserving relevant information.
   - This layer is central to architecture because it determines what the model sees and how “@”-mentions, note references, and extracted content are represented.

9. **Vault search and retrieval**
   - `src/search/**` provides the retrieval system used by chat, vault QA, project mode, and agent tools.
   - There are multiple retrieval backends and generations: newer `search/v3/**` full-text/lexical/scoring pipelines, plus index-backed semantic retrieval via `indexBackend/**`, `vectorStoreManager.ts`, and `RetrieverFactory.ts`.
   - The search flow is: vault/index events → chunking/scoring/index storage → query expansion and retrieval → merged results → citation/search result formatting into chat context or tool output.

10. **Indexing and vault event handling**
    - `src/search/indexEventHandler.ts`, `indexOperations.ts`, `indexSignal.ts`, and `projectLoadTracker.ts` connect Obsidian vault changes to search/index maintenance.
    - Caches under `src/cache/**` and project context cache logic help avoid recomputing expensive file or context extraction work.
    - This is important for architecture diagrams because search is not just query-time; it is fed by background indexing and file-change signals.

11. **Project, memory, and prompt systems**
    - `src/contexts/**`, `src/memory/**`, `src/system-prompts/**`, and `src/commands/**` represent higher-level product features built on top of context/search/tools.
    - Project mode structures sources by folder/tag; long-term memory persists user-specific knowledge; system prompts and custom commands define reusable behaviors.
    - These subsystems are mostly configuration-and-content driven, which fits the plugin’s “notes as configuration” philosophy.

12. **Editor and workspace integration**
    - `src/editor/**` contains selection highlights, quick-ask editor extensions, guard rails for replacements, and note selection behavior.
    - `src/services/webViewerService/**` and `src/services/obsidianCli/**` integrate with external surfaces like web tabs and the Obsidian CLI.
    - This layer mediates actions across the host app: note editor, active file, selection, tabs, and browser/web content.

13. **Settings, models, and feature flags**
    - `src/settings/**` and `src/components/ui/**` provide a large settings surface for provider keys, model parameters, agent features, plus-tier options, and tool toggles.
    - `aiParams.ts`, `model.ts`, `providerModels.ts`, and related utilities govern per-model parameters and capabilities.
    - Configuration is not peripheral here; it drives which providers, tools, retrieval modes, and premium features are active.

14. **External dependencies and service boundaries**
    - Primary external boundary is to **LLM providers** selected by the user.
    - Secondary external services include **Brevilabs/Copilot Plus** features, which the README says may use networked backend services for premium agent/file-conversion workflows.
    - The plugin also relies on Obsidian itself for vault access, UI hosting, editor selection, and community-plugin lifecycle.

15. **Operational concerns**
    - The repo includes extensive tests around retrieval, prompt building, parsing, tool execution, and chat behavior, which suggests the architecture is optimized for correctness at the boundaries where model output meets app state.
    - Scripts, release workflows, and build tooling (`esbuild`, Jest, GitHub Actions) support a packaged plugin distribution rather than a standalone server.

Main entry points: [`src/main.ts`](https://github.com/logancyang/obsidian-copilot/blob/master/src/main.ts) (Plugin entry), [`src/core/ChatManager.ts`](https://github.com/logancyang/obsidian-copilot/blob/master/src/core/ChatManager.ts) (Chat manager), [`src/tools/ToolRegistry.ts`](https://github.com/logancyang/obsidian-copilot/blob/master/src/tools/ToolRegistry.ts) (Tool registry), [`src/LLMProviders/chainRunner/index.ts`](https://github.com/logancyang/obsidian-copilot/blob/master/src/LLMProviders/chainRunner/index.ts) (Chain runners)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_obsidian["Obsidian boundary"]
  node_main["Plugin entry<br/>obsidian plugin<br/>[main.ts]"]
  node_editor["Editor bridge<br/>workspace integration<br/>[index.ts]"]
  node_webviewer["Web viewer<br/>surface bridge"]
end

subgraph group_ui["User interface"]
  node_chatview["Chat view<br/>React surface<br/>[Chat.tsx]"]
  node_copilotview["Copilot view<br/>React surface<br/>[CopilotView.tsx]"]
  node_quickask["Quick ask<br/>overlay UI<br/>[index.ts]"]
end

subgraph group_engine["Conversation engine"]
  node_chatcore["Chat manager<br/>conversation core<br/>[ChatManager.ts]"]
  node_context["Context engine<br/>prompt context"]
end

subgraph group_llm["LLM runtime"]
  node_providers["Model layer<br/>llm adapters"]
  node_chains["Chain runners<br/>agent execution<br/>[index.ts]"]
end

subgraph group_retrieval["Retrieval pipeline"]
  node_search["Search core<br/>retrieval pipeline<br/>[SearchCore.ts]"]
  node_indexing["Indexing loop<br/>vault indexing"]
end

subgraph group_tools["Tools"]
  node_toolsreg["Tool registry<br/>tool dispatch<br/>[ToolRegistry.ts]"]
  node_noteops["Note tools<br/>vault actions<br/>[NoteTools.ts]"]
  node_cliweb["CLI and web tools<br/>external actions"]
end

subgraph group_config["Configuration"]
  node_settings["Settings UI<br/>configuration surface<br/>[SettingsMainV2.tsx]"]
  node_prompts["Prompt system<br/>prompt management"]
  node_commands["Commands<br/>command layer<br/>[index.ts]"]
end

node_main -->|"mounts"| node_chatview
node_main -->|"mounts"| node_copilotview
node_main -->|"enables"| node_quickask
node_main -->|"integrates"| node_editor
node_main -->|"registers"| node_commands
node_main -->|"configures"| node_settings
node_main -->|"owns"| node_chatcore
node_chatview -->|"uses"| node_chatcore
node_quickask -->|"uses"| node_chatcore
node_chatcore -->|"builds with"| node_context
node_chatcore -->|"executes"| node_chains
node_chains -->|"streams from"| node_providers
node_chains -->|"invokes"| node_toolsreg
node_chains -->|"retrieves via"| node_search
node_providers -->|"supports"| node_search
node_search -->|"fed by"| node_indexing
node_context -->|"consumes"| node_search
node_toolsreg -->|"dispatches"| node_noteops
node_toolsreg -->|"dispatches"| node_cliweb
node_commands -->|"uses"| node_prompts
node_settings -->|"selects"| node_providers
node_settings -->|"toggles"| node_toolsreg
node_editor -->|"launches"| node_quickask
node_webviewer -->|"feeds"| node_toolsreg

click node_main "https://github.com/logancyang/obsidian-copilot/blob/master/src/main.ts"
click node_editor "https://github.com/logancyang/obsidian-copilot/blob/master/src/editor/index.ts"
click node_webviewer "https://github.com/logancyang/obsidian-copilot/blob/master/src/services/webViewerService/webViewerService.ts"
click node_chatview "https://github.com/logancyang/obsidian-copilot/blob/master/src/components/Chat.tsx"
click node_copilotview "https://github.com/logancyang/obsidian-copilot/blob/master/src/components/CopilotView.tsx"
click node_quickask "https://github.com/logancyang/obsidian-copilot/blob/master/src/components/quick-ask/index.ts"
click node_settings "https://github.com/logancyang/obsidian-copilot/blob/master/src/settings/v2/SettingsMainV2.tsx"
click node_prompts "https://github.com/logancyang/obsidian-copilot/blob/master/src/system-prompts/systemPromptManager.ts"
click node_commands "https://github.com/logancyang/obsidian-copilot/blob/master/src/commands/index.ts"
click node_chatcore "https://github.com/logancyang/obsidian-copilot/blob/master/src/core/ChatManager.ts"
click node_context "https://github.com/logancyang/obsidian-copilot/blob/master/src/context/PromptContextEngine.ts"
click node_providers "https://github.com/logancyang/obsidian-copilot/blob/master/src/LLMProviders/chatModelManager.ts"
click node_chains "https://github.com/logancyang/obsidian-copilot/blob/master/src/LLMProviders/chainRunner/index.ts"
click node_search "https://github.com/logancyang/obsidian-copilot/blob/master/src/search/v3/SearchCore.ts"
click node_indexing "https://github.com/logancyang/obsidian-copilot/blob/master/src/search/indexEventHandler.ts"
click node_toolsreg "https://github.com/logancyang/obsidian-copilot/blob/master/src/tools/ToolRegistry.ts"
click node_noteops "https://github.com/logancyang/obsidian-copilot/blob/master/src/tools/NoteTools.ts"
click node_cliweb "https://github.com/logancyang/obsidian-copilot/blob/master/src/tools/ObsidianCliTools.ts"

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_main,node_editor,node_webviewer,node_settings,node_prompts,node_commands toneBlue
class node_chatview,node_copilotview,node_quickask toneAmber
class node_chatcore,node_context toneMint
class node_providers,node_chains toneRose
class node_search,node_indexing toneIndigo
class node_toolsreg,node_noteops,node_cliweb toneTeal
```

## Components

### Obsidian boundary

Plugin lifecycle and host-app integration points.

- [Plugin entry](https://github.com/logancyang/obsidian-copilot/blob/master/src/main.ts): obsidian plugin · Wires lifecycle hooks, settings, commands, UI surfaces, and core services. · `src/main.ts`
- [Editor bridge](https://github.com/logancyang/obsidian-copilot/blob/master/src/editor/index.ts): workspace integration · Selection highlights, quick-ask editor extensions, and replacement guards. · `src/editor/index.ts`
- [Web viewer](https://github.com/logancyang/obsidian-copilot/blob/master/src/services/webViewerService/webViewerService.ts): surface bridge · Coordinates web-tab state and browser-facing actions. · `src/services/webViewerService/webViewerService.ts`

### User interface

Chat, quick-ask, settings, and modal surfaces.

- [Chat view](https://github.com/logancyang/obsidian-copilot/blob/master/src/components/Chat.tsx): React surface · Primary conversational UI and layout entry point. · `src/components/Chat.tsx`
- [Copilot view](https://github.com/logancyang/obsidian-copilot/blob/master/src/components/CopilotView.tsx): React surface · Secondary workspace view for agentic and chat workflows. · `src/components/CopilotView.tsx`
- [Quick ask](https://github.com/logancyang/obsidian-copilot/blob/master/src/components/quick-ask/index.ts): overlay UI · Inline ask/edit surface with mode switching and lightweight sessions. · `src/components/quick-ask/index.ts`

### Conversation engine

Chat state, streaming, context assembly, and prompt orchestration.

- [Chat manager](https://github.com/logancyang/obsidian-copilot/blob/master/src/core/ChatManager.ts): conversation core · Owns message lifecycle, persistence, and streaming session coordination. · `src/core/ChatManager.ts`
- [Context engine](https://github.com/logancyang/obsidian-copilot/blob/master/src/context/PromptContextEngine.ts): prompt context · Builds and compacts vault, note, selection, and chat history into prompts. · `src/context/PromptContextEngine.ts`

### LLM runtime

Provider adapters, model selection, and chain execution modes.

- [Model layer](https://github.com/logancyang/obsidian-copilot/blob/master/src/LLMProviders/chatModelManager.ts): llm adapters · Normalizes provider backends behind a common chat and embedding interface. · `src/LLMProviders/chatModelManager.ts`
- [Chain runners](https://github.com/logancyang/obsidian-copilot/blob/master/src/LLMProviders/chainRunner/index.ts): agent execution · Runs chat, project QA, vault QA, copilot-plus, and autonomous agent flows. · `src/LLMProviders/chainRunner/index.ts`

### Retrieval pipeline

Search, indexing, and vault QA grounding.

- [Search core](https://github.com/logancyang/obsidian-copilot/blob/master/src/search/v3/SearchCore.ts): retrieval pipeline · Query, merge, scoring, and lexical/semantic retrieval over vault content. · `src/search/v3/SearchCore.ts`
- [Indexing loop](https://github.com/logancyang/obsidian-copilot/blob/master/src/search/indexEventHandler.ts): vault indexing · Connects vault change signals to index maintenance and project tracking. · `src/search/indexEventHandler.ts`

### Tools

Model-exposed actions for vault, editor, and external systems.

- [Tool registry](https://github.com/logancyang/obsidian-copilot/blob/master/src/tools/ToolRegistry.ts): tool dispatch · Registers and dispatches model-facing tools for vault, editor, memory, and external actions. · `src/tools/ToolRegistry.ts`
- [Note tools](https://github.com/logancyang/obsidian-copilot/blob/master/src/tools/NoteTools.ts): vault actions · Search, read, file-tree, tag, date, and note/file manipulation capabilities. · `src/tools/NoteTools.ts`
- [CLI and web tools](https://github.com/logancyang/obsidian-copilot/blob/master/src/tools/ObsidianCliTools.ts): external actions · Obsidian CLI-backed actions, YouTube handling, and web-related integrations. · `src/tools/ObsidianCliTools.ts`

### Configuration

Settings, prompts, custom commands, and product features.

- [Settings UI](https://github.com/logancyang/obsidian-copilot/blob/master/src/settings/v2/SettingsMainV2.tsx): configuration surface · Settings pages for providers, models, tools, QA, and premium options. · `src/settings/v2/SettingsMainV2.tsx`
- [Prompt system](https://github.com/logancyang/obsidian-copilot/blob/master/src/system-prompts/systemPromptManager.ts): prompt management · System prompts, custom prompt registration, and reusable behavioral templates. · `src/system-prompts/systemPromptManager.ts`
- [Commands](https://github.com/logancyang/obsidian-copilot/blob/master/src/commands/index.ts): command layer · Custom commands, context-menu actions, and modal-driven command flows. · `src/commands/index.ts`

## Connections

- Plugin entry → Chat view: mounts · Hosts the main chat surface inside Obsidian.
- Plugin entry → Copilot view: mounts · Registers the copilot workspace view.
- Plugin entry → Quick ask: enables · Hooks quick-ask overlays and editor triggers.
- Plugin entry → Editor bridge: integrates · Connects plugin actions to editor and selection state.
- Plugin entry → Commands: registers · Installs command palette and context-menu actions.
- Plugin entry → Settings UI: configures · Exposes settings and feature toggles.
- Plugin entry → Chat manager: owns · Coordinates lifecycle and chat session services.
- Chat view → Chat manager: uses · Reads and drives conversation state.
- Quick ask → Chat manager: uses · Creates lightweight ask/edit sessions.
- Chat manager → Context engine: builds with · Turns user input and vault artifacts into model-ready context.
- Chat manager → Chain runners: executes · Dispatches requests into the selected runner mode.
- Chain runners → Model layer: streams from · Calls provider backends through normalized model interfaces.
- Chain runners → Tool registry: invokes · Executes tool calls during agentic and QA flows.
- Chain runners → Search core: retrieves via · Uses retrieval pipelines for QA, citations, and grounding.
- Model layer → Search core: supports · Model choice influences retrieval-enhanced workflows and embeddings.
- Search core → Indexing loop: fed by · Index maintenance responds to vault change events.
- Context engine → Search core: consumes · Embeds search results and note fragments into prompts.
- Tool registry → Note tools: dispatches · Routes vault and note-oriented actions.
- Tool registry → CLI and web tools: dispatches · Routes CLI-backed and web-related actions.
- Commands → Prompt system: uses · Commands and modal flows rely on prompt templates.
- Settings UI → Model layer: selects · Controls model keys, parameters, and provider choices.
- Settings UI → Tool registry: toggles · Enables or disables tool capabilities.
- Editor bridge → Quick ask: launches · Starts inline ask/edit interactions from selections.
- Web viewer → Tool registry: feeds · Provides tab and browser-derived actions to tools.
