# chhabrakadabra/logseq-plugin-copilot architecture

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

- Interactive diagram: https://gitdiagram.com/chhabrakadabra/logseq-plugin-copilot
- Repository: https://github.com/chhabrakadabra/logseq-plugin-copilot

## Overview

##### Project type and purpose
- This is a Logseq plugin—a single‑page, React + TypeScript application bundled with Vite—that embeds deep‑learning–powered chat (“Copilot”) into the Logseq note‑taking environment.
- Purpose: index a user’s entire Logseq graph, maintain a vector store of note embeddings, receive user queries, perform vector similarity search, augment prompts, and relay conversations to/from an OpenAI‑compatible API.

##### File structure
- Top level
- index.html, package.json, vite.config.ts, tsconfig.json, Tailwind & PostCSS configs → front‑end build
- .github/workflows/publish.yml → CI/CD for plugin packaging/publish
- src/
- src/ui → React components and styles for chat overlay
- src/lib → core logic modules:
– chat.ts (coordinates UI input → LLM API call)
– rag.ts (retrieval‑augmented generation: builds prompt with contexts)
– vectorStore.ts (manages IndexedDB/vector retrieval)
– logseq.ts (wraps Logseq plugin API calls)
– logger.ts (logging utility)
- src/workers/vectorStore.ts → Web Worker offloading embedding/indexing tasks
- src/main.tsx → application bootstrap: registers plugin, renders React UI component into Logseq

##### README for insights
- System relies on OpenAI API with configurable base URL/model.
- UI invoked via Ctrl‑P, displays chat overlay, uses vector similarity Top‑K.
- Plugin talks to OpenAI (or any API‑compatible LLM) and returns suggestions to insert into notes.

##### Final advice
- Be highly detailed: represent each interaction (event, function call, HTTP request).
- Integration points: plugin registration with Logseq, settings retrieval, worker messaging.
- Don’t overthink: break the system into discrete, well‑labeled components, show how data flows end‑to‑end from user keystroke to AI response insertion.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host & Bootstrap
    subgraph "Logseq Host & Plugin Init"
        direction TB
        LogseqHost["Logseq Host"]:::host
        PluginInit["Plugin Initialization"]:::host
    end

    LogseqHost -->|"Ctrl+P event"| PluginInit
    click PluginInit "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/src/main.tsx"

    %% UI Layer
    subgraph "UI Overlay" 
        direction TB
        EntryHTML["Entry HTML"]:::ui
        App["App.tsx (Root Component)"]:::ui
        Messages["Messages.tsx"]:::ui
        Placeholder["Placeholder.tsx"]:::ui
        Styles["style.css"]:::ui
    end

    PluginInit -->|"mount UI"| EntryHTML
    EntryHTML --> App
    App --> Messages
    App --> Placeholder
    App --- Styles

    click EntryHTML "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/index.html"
    click App "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/src/ui/App.tsx"
    click Messages "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/src/ui/Messages.tsx"
    click Placeholder "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/src/ui/Placeholder.tsx"
    click Styles "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/src/ui/style.css"

    %% Logic Modules
    subgraph "Core Logic Modules"
        direction TB
        Chat["chat.ts"]:::logic
        RAG["rag.ts"]:::logic
        VSInterface["vectorStore.ts"]:::logic
        LogseqAdapter["logseq.ts"]:::logic
        Logger["logger.ts"]:::logic
        Types["types.ts"]:::infra
    end

    App -->|"user query"| Chat
    Chat -->|"build prompt"| RAG
    RAG -->|"vector search"| VSInterface
    Chat -->|"insert suggestion"| LogseqAdapter
    Chat --> Logger
    RAG --> Logger
    VSInterface --> Logger
    Chat --> Types
    RAG --> Types

    click Chat "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/src/lib/chat.ts"
    click RAG "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/src/lib/rag.ts"
    click VSInterface "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/src/lib/vectorStore.ts"
    click LogseqAdapter "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/src/lib/logseq.ts"
    click Logger "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/src/lib/logger.ts"
    click Types "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/src/types.ts"

    %% Data Layer
    subgraph "Data & Workers"
        direction TB
        Worker["VectorStore Worker"]:::data
        IndexedDB["IndexedDB"]:::data
    end

    VSInterface -->|"postMessage"| Worker
    Worker --> IndexedDB
    Worker --> Logger
    VSInterface --> IndexedDB

    click Worker "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/src/workers/vectorStore.ts"

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI HTTP API"]:::external
    end

    Chat -->|"HTTP request"| OpenAI
    OpenAI -->|"response"| Chat

    %% Infrastructure & Config
    subgraph "Infrastructure & Config"
        direction TB
        ViteConfig["vite.config.ts"]:::infra
        TailwindConfig["tailwind.config.js"]:::infra
        PostCSSConfig["postcss.config.js"]:::infra
        CI["publish.yml"]:::infra
        Package["package.json"]:::infra
        Readme["README.md"]:::infra
    end

    click ViteConfig "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/vite.config.ts"
    click TailwindConfig "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/tailwind.config.js"
    click PostCSSConfig "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/postcss.config.js"
    click CI "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/.github/workflows/publish.yml"
    click Package "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/package.json"
    click Readme "https://github.com/chhabrakadabra/logseq-plugin-copilot/blob/main/README.md"

    %% Styles
    classDef host fill:#CCE5FF,stroke:#3399FF,color:#000
    classDef ui fill:#E6FFE6,stroke:#33CC33,color:#000
    classDef logic fill:#FFE6CC,stroke:#FF9933,color:#000
    classDef data fill:#FFF2CC,stroke:#FFCC00,color:#000
    classDef external fill:#F3E6FF,stroke:#CC33FF,color:#000
    classDef infra fill:#F2F2F2,stroke:#999999,color:#000
```
