How smallcloudai/refact-intellij works
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