# smallcloudai/refact-intellij architecture

> Architecture diagram of the GitHub repository smallcloudai/refact-intellij, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smallcloudai/refact-intellij
- Repository: https://github.com/smallcloudai/refact-intellij

## Overview

##### Project type and purpose
- This is a JetBrains IntelliJ plugin (“Refact-intellij”) that provides AI-powered code assistance (code completion, CodeLens insights, diff views, shared chat pane, FIM debug page) by communicating with external LLMs or LSP servers.

##### File structure
- Top-level build files: Gradle (build.gradle.kts, settings.gradle.kts), plugin descriptor (src/main/resources/META-INF/plugin.xml).
- Core Kotlin source under `src/main/kotlin/com/smallcloud/refactai` organized into subpackages:
- ui and IDE integration modules: `status_bar`, `code_lens`, `panes/sharedchat`, `notifications`, `settings`, `statistic`
- event handling: `listeners`
- business logic: `account`, `modes` (completion, diff), `struct` (data models)
- IO layer: `io` (Connection, AsyncConnection, CloudMessageService, Fetch, RequestHelpers)
- LSP integration: `lsp` (LSPProcessHolder, LSPConfig, LSPHelper, Capabilities, ActiveDocNotifier)
- utilities: `utils`
- Tests mirror key modules (io, lsp, panes/sharedchat).

##### Key insights from README
- Plugin loaded into IntelliJ; user interacts via status bar, side bar, inline code lenses.
- Features include multi-LLM support, CodeLens, debugging page (FIM), image uploads, in-IDE shared chat.

##### Main components
A. IntelliJ Platform Host
- Plugin loader (plugin.xml)
- Extension points (status bar widget, tool window, editor code lens)
B. Plugin Core Services
- Initialization & state: `Initializer`, `PluginState`, `UpdateChecker`, `PluginErrorReportSubmitter`
- Account management: `AccountManager`, `AccountManagerChangedNotifier`
- Settings: `AppSettingsComponent`, `Host`, `AppSettingsState`
- Usage statistics & notifications
C. Event & Action Layer
- Event listeners (`listeners/*`): document, caret, focus, accept/cancel actions
- Actions invoke code completion or chat requests
D. UI Modules
- CodeLens provider & invalidator (`code_lens`)
- Inline completion UI (`codecompletion`)
- Diff view renderer (`modes/diff/renderer`)
- Shared chat tool window (JCEF-based webview under `panes/sharedchat/browser`)
- Status bar widget (`status_bar`)
E. Mode Engines
- Completion mode (`modes/completion`): prompts, trackers, stubs
- Diff mode (`modes/diff`)
F. IO & Network Layer
- Synchronous/Asynchronous connection abstractions (`Connection`, `AsyncConnection`)
- CloudMessageService: HTTP calls to LLM endpoints
- Fetch & RequestHelpers
- Inference context & notifier
G. LSP Integration
- LSPProcessHolder: spawn/manage external LSP server processes
- LSPConfig, LSPHelper, LSPTools, capabilities negotiation, active-doc notifier
H. External Systems
- Hosted LLM APIs (OpenAI, Refact/1.6B, Code Llama, etc.)
- Self-hosted LSP servers
- FIM debug page backend (if applicable)

##### Relationships and interactions
- User triggers an action in the IDE UI → Event listener → Core service routes request
- Core service invokes IO layer → AsyncConnection or CloudMessageService → external LLM API
- For LSP mode: Core service requests LSPProcessHolder to send & receive LSP messages
- Responses flow back to Mode Engines → UI Modules render completions/diffs/chat
- AccountManager enforces authentication; Settings influence host/endpoint URLs
- PluginErrorReportSubmitter forwards errors to remote logging endpoint

##### Architectural patterns & design principles
- Modular separation: UI, event handling, business logic, IO, external integration
- Asynchronous, non-blocking IO with notifier patterns
- Factory/provider pattern for CodeLens, tool windows, modes
- Extension-based integration with IntelliJ’s plugin API
- Clear domain models (`struct`) decoupled from transport

##### Diagramming recommendations
- IntelliJ Host (plugin loader & extension points)
- Core Services
- Event/Action Layer
- UI Components
- Mode Engines
- IO & Network
- LSP Integration
- External Services
- Data flow (e.g., event → core → IO → external → UI)
- Control flow (e.g., LSP command → LSPProcess → plugin)
- IDE/Platform (grey)
- Plugin-internal modules (blue)
- External systems (green)
- Rounded rectangles for UI components
- Standard rectangles for service modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "IntelliJ Platform Host"
        HostLoad["Plugin Loader\n(plugin.xml)"]:::ide
        ExtPoints["Extension Points\n(StatusBar, ToolWindow, CodeLens)"]:::ide
    end

    subgraph "Plugin Core Services"
        Init["Initializer"]:::core
        State["PluginState"]:::core
        Upd["UpdateChecker"]:::core
        Err["PluginErrorReportSubmitter"]:::core
        AccMod["AccountManager"]:::core
        AccNot["AccountManagerChangedNotifier"]:::core
        SetComp["AppSettingsComponent"]:::core
        SetConf["AppSettingsConfigurable"]:::core
        SetState["AppSettingsState"]:::core
        HostCfg["Host"]:::core
        Usage["UsageStatistic/UsageStats"]:::core
        Notif["Notifications"]:::core
    end

    subgraph "Event & Action Layer"
        Listeners["Listeners (Document, Caret, Actions)"]:::core
    end

    subgraph "UI Modules"
        CodeLens["CodeLens Provider"]:::ui
        InlineComp["Inline Completion UI"]:::ui
        DiffUI["Diff View Renderer"]:::ui
        ChatUI["Shared Chat Tool Window"]:::ui
        StatusBar["Status Bar Widget"]:::ui
    end

    subgraph "Mode Engines"
        CompMode["Completion Mode"]:::core
        DiffMode["Diff Mode"]:::core
    end

    subgraph "IO & Network Layer"
        Conn["Connection / AsyncConnection"]:::core
        CMS["CloudMessageService"]:::core
        Fetch["Fetch / RequestHelpers"]:::core
        Inference["Inference Context & Notifier"]:::core
    end

    subgraph "LSP Integration"
        ProcHolder["LSPProcessHolder"]:::core
        LSPCfg["LSPConfig"]:::core
        LSPH["LSPHelper"]:::core
        LSPTools["LSPTools"]:::core
        LSPCap["Capabilities"]:::core
        LSPDoc["ActiveDoc Notifier"]:::core
    end

    subgraph "External Systems"
        HTTPAPI["LLM HTTP APIs"]:::external
        LSPServer["Self-hosted LSP Servers"]:::external
    end

    HostLoad --> ExtPoints
    ExtPoints --> Listeners
    Listeners --> Init
    Init --> State
    State --> AccMod
    AccMod --> AccNot
    State --> SetComp
    SetComp --> SetConf
    SetComp --> SetState
    SetConf --> HostCfg
    State --> Usage
    Init --> Notif

    Listeners --> CompMode
    Listeners --> DiffMode
    Listeners --> ChatUI

    CompMode -->|"HTTP/JSON"| CMS
    DiffMode -->|"HTTP/JSON"| CMS
    ChatUI -->|"HTTP/JSON"| CMS

    CMS --> Fetch
    Fetch --> Conn
    Conn --> CompMode
    Conn --> DiffMode
    Conn --> ChatUI

    CompMode -->|"UI update"| InlineComp
    CompMode -->|"UI update"| CodeLens
    DiffMode -->|"UI update"| DiffUI
    ChatUI -->|"render"| StatusBar

    CompMode -->|"LSP call"| ProcHolder
    DiffMode -->|"LSP call"| ProcHolder

    ProcHolder -->|"LSP JSON-RPC"| LSPServer
    LSPCfg --> ProcHolder
    LSPH --> ProcHolder
    LSPTools --> ProcHolder
    LSPCap --> ProcHolder
    LSPDoc --> ProcHolder

    classDef ide fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef ui fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px

    click HostLoad "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/resources/META-INF/plugin.xml"
    click Init "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/Initializer.kt"
    click State "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/PluginState.kt"
    click Upd "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/UpdateChecker.kt"
    click Err "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/PluginErrorReportSubmitter.kt"
    click AccMod "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/account/AccountManager.kt"
    click AccNot "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/account/AccountManagerChangedNotifier.kt"
    click SetComp "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/settings/AppSettingsComponent.kt"
    click SetConf "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/settings/AppSettingsConfigurable.kt"
    click SetState "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/settings/AppSettingsState.kt"
    click HostCfg "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/settings/Host.kt"
    click Usage "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/statistic/UsageStatistic.kt"
    click Usage "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/statistic/UsageStats.kt"
    click Notif "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/notifications/Initializer.kt"
    click Notif "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/notifications/Notifications.kt"
    click Listeners "https://github.com/smallcloudai/refact-intellij/tree/main/src/main/kotlin/com/smallcloud/refactai/listeners"
    click CodeLens "https://github.com/smallcloudai/refact-intellij/tree/main/src/main/kotlin/com/smallcloud/refactai/code_lens"
    click InlineComp "https://github.com/smallcloudai/refact-intellij/tree/main/src/main/kotlin/com/smallcloud/refactai/codecompletion"
    click DiffUI "https://github.com/smallcloudai/refact-intellij/tree/main/src/main/kotlin/com/smallcloud/refactai/modes/diff/renderer"
    click ChatUI "https://github.com/smallcloudai/refact-intellij/tree/main/src/main/kotlin/com/smallcloud/refactai/panes/sharedchat/browser"
    click StatusBar "https://github.com/smallcloudai/refact-intellij/tree/main/src/main/kotlin/com/smallcloud/refactai/status_bar"
    click CompMode "https://github.com/smallcloudai/refact-intellij/tree/main/src/main/kotlin/com/smallcloud/refactai/modes/completion"
    click DiffMode "https://github.com/smallcloudai/refact-intellij/tree/main/src/main/kotlin/com/smallcloud/refactai/modes/diff"
    click Conn "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/io/Connection.kt"
    click Conn "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/io/AsyncConnection.kt"
    click CMS "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/io/CloudMessageService.kt"
    click Fetch "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/io/Fetch.kt"
    click Fetch "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/io/RequestHelpers.kt"
    click Inference "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/io/InferenceGlobalContext.kt"
    click Inference "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/io/InferenceGlobalContextChangedNotifier.kt"
    click ProcHolder "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/lsp/LSPProcessHolder.kt"
    click LSPCfg "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/lsp/LSPConfig.kt"
    click LSPH "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/lsp/LSPHelper.kt"
    click LSPTools "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/lsp/LSPTools.kt"
    click LSPCap "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/lsp/LSPCapabilities.kt"
    click LSPDoc "https://github.com/smallcloudai/refact-intellij/blob/main/src/main/kotlin/com/smallcloud/refactai/lsp/LSPActiveDocNotifierService.kt"
```
