# briansunter/logseq-plugin-gpt3-openai architecture

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

- Interactive diagram: https://gitdiagram.com/briansunter/logseq-plugin-gpt3-openai
- Repository: https://github.com/briansunter/logseq-plugin-gpt3-openai

## Overview

##### Main Components

- Plugin UI Layer – This is represented in the “src/ui” directory. It includes several UI components (e.g., CommandButton, CommandOption, CommandToolbar, and various result display components) that allow users to interact with and trigger commands like “gpt”, “gpt-page”, “gpt-block”, “whisper” and “dalle”.
- Plugin Core / Logic Layer – Located in “src/lib”, this layer includes modules such as logseq.ts (integration with Logseq APIs), openai.ts (communication with the OpenAI API), prompts.ts (handling built-in prompt templates), rawCommands.ts (command processing), and settings.ts (configuration and user settings).
- Prompt Template/Configuration Layer – The “src/prompts” directory holds prompt templates that are used to generate the appropriate text responses. These are engaged when users create custom or built-in prompt templates.
- Build & Deployment Infrastructure – Files like “package.json”, “vite.config.ts”, “pnpm-lock.yaml”, and configuration files (Tailwind, PostCSS, etc.) indicate the build pipeline and deployment setup using Vite and semantic-release for deployment.

##### Relationships and Interactions

- User Actions and UI:
– The user interacts with the Logseq interface and invokes commands (via keystroke shortcuts or menu selections).
– This invokes one or more UI components (in “src/ui”) such as the gpt popup, command buttons, or command results display.

- UI and Plugin Logic:
– The UI layer calls functions from the core logic (in “src/lib”). For example, when a command is invoked, the corresponding logic in rawCommands.ts or the API handling in openai.ts is triggered.
– Settings in settings.ts influence how data is sent to the OpenAI API, such as specifying the model (gpt-3.5-turbo, text-davinci-003, or gpt-4) and custom parameters like a chat prompt policy.

- Communication with External Services (OpenAI):
– The openai.ts module manages API requests to OpenAI (and possibly OpenAI’s DALL-E and Whisper endpoints) and formats responses to send back to the UI.
– Data flow is bi-directional: the UI sends the prompt to the core logic, which then uses openai.ts to retrieve responses, and the responses are then rendered on the UI.

- Template and Prompt Management:
– The “src/prompts” directory provides the built-in templates, and users can define their custom templates with a `prompt-template::` property in Logseq, which is processed via the prompts.ts module.

##### Architectural Patterns and Design Principles

- Separation of Concerns: The system cleanly separates the UI from business logic (API interaction, prompt management, and command processing).
- Modular Design: Each directory (ui, lib, prompts) encapsulates specific aspects of functionality, easing testing and maintenance.
- Event-Driven Interactions: User events (such as invoking a GPT command) drive the interaction chain, from the UI component to the API call.
- Integration with External APIs: Standardized communication via modules ensures that the plugin’s external dependencies (OpenAI and Logseq) are abstracted and cleanly managed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User / Logseq Editor"]:::user

    UI["UI Layer (src/ui)"]:::ui
    UI -->|"contains"| UI_Components

    subgraph UI_Components[ ]
        CommandButton["CommandButton (CommandButton.tsx)"]:::uiComp
        CommandOption["CommandOption (CommandOption.tsx)"]:::uiComp
        CommandResult["CommandResult (CommandResult.tsx)"]:::uiComp
        CommandToolbar["CommandToolbar (CommandToolbar.tsx)"]:::uiComp
        ErrorResult["ErrorResult (ErrorResult.tsx)"]:::uiComp
        LoadingResult["LoadingResult (LoadingResult.tsx)"]:::uiComp
        SuccessResult["SuccessResult (SuccessResult.tsx)"]:::uiComp
    end

    CL["Core Logic Layer (src/lib)"]:::core
    subgraph Core_Modules[ ]
        Logseq["logseq.ts"]:::coreMod
        Openai["openai.ts"]:::coreMod
        Prompts["prompts.ts"]:::coreMod
        RawCommands["rawCommands.ts"]:::coreMod
        Settings["settings.ts"]:::coreMod
    end

    ExtAPI["OpenAI API Services\n(GPT: gpt-3.5-turbo, text-davinci-003, gpt-4; DALL-E & Whisper)"]:::external

    PT["Prompt Templates (src/prompts)"]:::prompt
    PT_File["prompts.toml"]:::promptFile

    Build["Build & Deployment Infrastructure"]:::build
    BuildFiles["package.json, vite.config.ts, pnpm-lock.yaml, tailwind.config.js, postcss.config.js"]:::buildFiles

    U -->|"invokes"| UI
    UI -->|"triggers"| CL
    CL -->|"calls"| ExtAPI
    PT -->|"supplies prompts to"| CL
    PT -->|"includes"| PT_File
    CL -->|"returns responses to"| UI

    Build -->|"defines build pipeline"| BuildFiles

    classDef user fill:#f9f,stroke:#333,stroke-width:2px;
    classDef ui fill:#ccf,stroke:#333,stroke-width:2px;
    classDef uiComp fill:#bbf,stroke:#333,stroke-width:1px;
    classDef core fill:#cfc,stroke:#333,stroke-width:2px;
    classDef coreMod fill:#afa,stroke:#333,stroke-width:1px;
    classDef external fill:#fcc,stroke:#333,stroke-width:2px;
    classDef prompt fill:#fcf,stroke:#333,stroke-width:2px;
    classDef promptFile fill:#f9c,stroke:#333,stroke-width:1px;
    classDef build fill:#cff,stroke:#333,stroke-width:2px;
    classDef buildFiles fill:#9cf,stroke:#333,stroke-width:1px;

    click UI "https://github.com/briansunter/logseq-plugin-gpt3-openai/tree/master/src/ui"
    click CommandButton "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/src/ui/components/CommandButton.tsx"
    click CommandOption "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/src/ui/components/CommandOption.tsx"
    click CommandResult "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/src/ui/components/CommandResult.tsx"
    click CommandToolbar "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/src/ui/components/CommandToolbar.tsx"
    click ErrorResult "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/src/ui/components/ErrorResult.tsx"
    click LoadingResult "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/src/ui/components/LoadingResult.tsx"
    click SuccessResult "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/src/ui/components/SuccessResult.tsx"

    click CL "https://github.com/briansunter/logseq-plugin-gpt3-openai/tree/master/src/lib"
    click Logseq "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/src/lib/logseq.ts"
    click Openai "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/src/lib/openai.ts"
    click Prompts "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/src/lib/prompts.ts"
    click RawCommands "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/src/lib/rawCommands.ts"
    click Settings "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/src/lib/settings.ts"

    click PT "https://github.com/briansunter/logseq-plugin-gpt3-openai/tree/master/src/prompts"
    click PT_File "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/src/prompts/prompts.toml"

    click BuildFiles "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/package.json"
    click BuildFiles "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/vite.config.ts"
    click BuildFiles "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/pnpm-lock.yaml"
    click BuildFiles "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/tailwind.config.js"
    click BuildFiles "https://github.com/briansunter/logseq-plugin-gpt3-openai/blob/master/postcss.config.js"
```
