# galihlprakoso/logseq-plugin-assistseq-ai-assistant architecture

> Architecture diagram of the GitHub repository galihlprakoso/logseq-plugin-assistseq-ai-assistant, 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/galihlprakoso/logseq-plugin-assistseq-ai-assistant
- Repository: https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant

## Overview

##### Project type and purpose
- This is a Logseq plugin (“AssistSeq”) built with React + TypeScript + Vite, intended to run embedded inside the Logseq desktop/web app.

##### File structure
- Top level:
- config files (.eslintrc.json, tailwind.config.js, vite.config.ts, etc.)
- README, demo assets, package.json, lockfile
- src/ hierarchy:
- screens – top‑level UI entry points (MainScreen, Onboarding, Terms)
- modules/chat – UI components (ChatBubble), state (useChatStore), hooks (useChat), prompts/constants
- modules/langchain – React context provider, hooks, abstractions for document retrievers, storage adapters, tools (cheerio, Tavily, LogSeq search)
- modules/logseq – adapters to the Logseq host API (services: get‑current‑page, append‑block, get‑graph; hooks for settings/UI control; stores for settings)
- modules/navigation, modules/shared – shared UI components (Card, DiagramRenderer, MarkdownRenderer), service helpers (copy to clipboard), navigation store
- Build & deployment: Vite (vite.config.ts), PostCSS, tailwind, CI/CD workflows (GitHub Actions), release tooling.

##### README for additional insights
- Core features: Contextual conversation, smart visualization, search engine integration, web scraping
- Supported external LLM providers

1. Browser/Logseq Host Environment
– Loads the plugin’s index.html + bundled JS (main.tsx → App.tsx)
– Exposes the Logseq JS API
2. UI Layer (React)
– screens/ (MainScreen, Onboarding, Terms)
– chat components (ChatBubble), navigation view, shared components (Card, MarkdownRenderer, DiagramRenderer, LoadingIndicator)
3. State & Business Logic
– Chat Store & Hooks (useChatStore, useChat)
– LangChain Context Provider & Hooks (useLangChain)
– Settings Store, Navigation Store
4. Data Access & Services
– modules/logseq/services: get‑current‑page, get‑documents, append block, get‑graph
– modules/langchain/libs/document-retrievers: LogSeqRelatedDocumentRetriever
– modules/langchain/tools: web scrapper (cheerio), Tavily search, Logseq query
– modules/langchain/libs/storage: LocalStorageStore
5. External Systems
– Logseq App (graph + plugin host API)
– LLM Providers (OpenAI, Gemini, Ollama, Groq)
– Tavily Search Engine API
– Third‑party websites (for web scraping)

b. Relationships & data flow
1. User interacts with the React UI →
2. UI invokes Chat Hooks →
3. Chat Hooks call LangChain Hooks / Context →
4. LangChain orchestrates:
- Retriever fetches Logseq context via Logseq services
- Optionally scrapes web pages or calls Tavily
- Aggregates context, stores scratch data (LocalStorage)
- Sends request to selected LLM provider → receives response
6. For persistence/updates, services call Logseq API to append blocks or update pages

c. Architectural patterns & principles
- Component-based UI (React)
- Context Providers (LangChainContextProvider) for cross‑cutting concerns
- Hooks + Zustand-like stores for state management (separation of state from view)
- Clear separation of concerns: UI / state / domain logic (retrievers, tools) / external interfaces

d. Key technologies & libraries
- React + TypeScript + Vite + Tailwind CSS
- Zustand or custom store hooks for state
- LangChain abstractions for LLM orchestration
- Cheerio for DOM parsing (web scraping)
- Tavily API for search
- Logseq JavaScript Plugin API for host integration

##### Summary & detail level
- Expose the key data paths: Logseq content ingestion, context assembly, LLM invocation, result rendering, page updates.
- Major configuration/build nodes (Vite bundler, Tailwind) off to the side if needed.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Environment
    Host["Browser / Logseq Host Environment\n(index.html, src/main.tsx, src/App.tsx)"]:::external

    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        MainScreen["MainScreen"]:::ui
        OnboardingScreen["OnboardingScreen"]:::ui
        TermsScreen["Terms and Conditions"]:::ui
        ChatBubble["ChatBubble UI"]:::ui
        NavigationView["NavigationView"]:::ui
        Card["Card"]:::ui
        DiagramRenderer["DiagramRenderer"]:::ui
        MarkdownRenderer["MarkdownRenderer"]:::ui
        LoadingIndicator["LoadingIndicator"]:::ui
        TextArea["TextArea"]:::ui
    end

    %% State & Business Logic
    subgraph "State & Business Logic"
        direction TB
        ChatStore["useChatStore"]:::state
        ChatHook["useChat"]:::state
        LangChainProvider["LangChainContextProvider"]:::state
        LangChainHook["useLangChain"]:::state
        SettingsStore["useSettingsStore"]:::state
        NavigationStore["useNavigationStore"]:::state
    end

    %% Services & Adapters
    subgraph "Data Access & Services"
        direction TB
        getCurrentPage["get-current-page"]:::service
        getDocuments["get-documents"]:::service
        getCurrentGraph["get-current-graph"]:::service
        appendBlock["append-block-to-page"]:::service
        controlUI["control-ui Hook"]:::service
        listenSettings["listen-settings Hook"]:::service
        Retriever["LogSeqRelatedDocumentRetriever"]:::service
        Storage["LocalStorageStore"]:::service
        Cheerio["Cheerio Scraper"]:::service
        TavilyTool["Tavily Search"]:::service
        LogseqQuery["Logseq Query Tool"]:::service
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        LogseqApp["Logseq App (Host API & Graph)"]:::external
        LLMs["LLM Providers\n(OpenAI, Gemini, Ollama, Groq)"]:::external
        TavilyAPI["Tavily Search API"]:::external
        WebPages["Third-party Web Pages"]:::external
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        direction TB
        ViteConfig["Vite Config"]:::config
        TailwindConfig["Tailwind Config"]:::config
        PostCSSConfig["PostCSS Config"]:::config
    end

    %% Connections
    Host -->|"loads UI bundle"| MainScreen
    Host --> OnboardingScreen
    Host --> TermsScreen

    MainScreen -->|interacts| ChatHook
    OnboardingScreen -->|interacts| SettingsStore
    TermsScreen -->|interacts| SettingsStore

    ChatHook --> ChatStore
    ChatHook --> LangChainHook

    LangChainHook --> LangChainProvider
    LangChainProvider --> Retriever
    LangChainProvider --> Storage
    LangChainProvider --> Cheerio
    LangChainProvider --> TavilyTool
    LangChainProvider --> LogseqQuery
    LangChainProvider --> LLMs

    Retriever -->|get context| getCurrentPage
    Retriever -->|get docs| getDocuments
    Retriever -->|graph| getCurrentGraph

    Cheerio -->|scrape| WebPages
    TavilyTool -->|search| TavilyAPI
    LogseqQuery -->|query| getDocuments

    ChatStore --> ChatBubble
    ChatStore --> DiagramRenderer
    ChatStore --> MarkdownRenderer
    ChatStore --> LoadingIndicator
    ChatStore --> TextArea
    ChatStore --> appendBlock
    appendBlock -->|update page| LogseqApp

    SettingsStore --> controlUI
    SettingsStore --> listenSettings
    controlUI --> LogseqApp
    listenSettings --> LogseqApp

    MainScreen --> NavigationView
    NavigationView --> NavigationStore

    ViteConfig --> Host
    TailwindConfig --> Host
    PostCSSConfig --> Host

    %% Click Events
    click Host "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/index.html"
    click Host "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/main.tsx"
    click Host "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/App.tsx"
    click MainScreen "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/screens/MainScreen.tsx"
    click OnboardingScreen "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/screens/OnboardingScreen.tsx"
    click TermsScreen "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/screens/TermsAndConditionsScreen.tsx"
    click ChatBubble "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/chat/components/ChatBubble.tsx"
    click NavigationView "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/navigation/components/NavigationView.tsx"
    click Card "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/shared/components/Card.tsx"
    click DiagramRenderer "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/shared/components/DiagramRenderer.tsx"
    click MarkdownRenderer "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/shared/components/MarkdownRenderer.tsx"
    click LoadingIndicator "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/shared/components/LoadingIndicator.tsx"
    click TextArea "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/shared/components/TextArea.tsx"
    click ChatStore "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/chat/stores/useChatStore.ts"
    click ChatHook "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/chat/hooks/useChat.ts"
    click LangChainProvider "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/langchain/components/LangChainContextProvider.tsx"
    click LangChainHook "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/langchain/hooks/useLangChain.ts"
    click SettingsStore "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/logseq/stores/useSettingsStore.ts"
    click NavigationStore "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/shared/stores/useNavigationStore.ts"
    click getCurrentPage "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/logseq/services/get-current-page.ts"
    click getDocuments "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/logseq/services/get-documents.ts"
    click getCurrentGraph "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/logseq/services/get-current-graph.ts"
    click appendBlock "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/logseq/services/append-block-to-page.ts"
    click controlUI "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/logseq/hooks/control-ui.ts"
    click listenSettings "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/logseq/hooks/listen-settings.ts"
    click Retriever "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/langchain/libs/document-retrievers/LogSeqRelatedDocumentRetreiver.ts"
    click Storage "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/langchain/libs/storage/LocaStorageStore.ts"
    click Cheerio "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/langchain/tools/cheerio.ts"
    click TavilyTool "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/langchain/tools/tavily.ts"
    click LogseqQuery "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/src/modules/langchain/tools/logseq-documents-search.ts"
    click ViteConfig "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/vite.config.ts"
    click TailwindConfig "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/tailwind.config.js"
    click PostCSSConfig "https://github.com/galihlprakoso/logseq-plugin-assistseq-ai-assistant/blob/master/postcss.config.js"

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#006064,color:#000
    classDef state fill:#E8F5E9,stroke:#2E7D32,color:#000
    classDef service fill:#FFF3E0,stroke:#EF6C00,color:#000
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#000
    classDef config fill:#F3E5F5,stroke:#6A1B9A,color:#000
```
