# f4cio/ensoplus architecture

> Architecture diagram of the GitHub repository f4cio/ensoplus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/f4cio/ensoplus
- Repository: https://github.com/f4cio/ensoplus

## Overview

#### Purpose and entry points
EnsoPlus is a Windows .NET alternative to the Enso command launcher: it collects commands and user work items, accepts keyboard-driven input, presents suggestions, and executes selected actions. The primary executable entry point is `EnsoPlus/Program.cs`; its main application surface is `EnsoPlus/FormMain.cs`. The solution is `CraftSynth.EnsoPlus.sln`.

#### Launcher composition and command contract
The core model separates command execution from command data. Provider contracts and command entities are defined in `EnsoPlus/Entities/ICommandsProvider.cs`, `EnsoPlus/Entities/Command.cs`, and `EnsoPlus/Entities/MergedCommand.cs`. Extension-facing contracts in `EnsoPlus/Entities/Extension/IEnsoExtension.cs` and `EnsoPlus/ExtensionPlus.cs` establish a boundary for adding launcher behavior without embedding it in the UI.

#### Command-provider execution layer
Feature-specific command providers implement launcher actions, including files, processes, web search, clipboard, macros, backups, calls, and database connection opening. Central coordination is likely `EnsoPlus/CommandsProviders/CommandsManager/CommandsManager.cs`; representative providers are `EnsoPlus/CommandsProviders/Opener/Opener.cs` and `EnsoPlus/CommandsProviders/WebSearcher/WebSearcher.cs`. Input resolution produces a command/action choice, then delegates execution to the relevant provider rather than directly to WinForms.

#### Work-item acquisition and persistence boundary
Work-item providers supply searchable user/domain data—shortcuts, bookmarks, contacts, macros, clipboard contents, process information, and command history—using `IWorkItem` entities. The provider side is rooted at `EnsoPlus/WorkItemsProviders/Shortcuts/Shortcuts.cs`, `EnsoPlus/WorkItemsProviders/CommandsHistory/CommandsHistory.cs`, and `EnsoPlus/WorkItemsProviders/Clipboard/ClipboardText.cs`; data types live under `EnsoPlus/Entities/WorkItems/`. This isolates discovery/storage concerns from command syntax and execution.

#### Input, selection, and suggestions flow
Keyboard and selection listeners capture context from the Windows desktop, then feed the launcher/suggestion workflow. Important stages are `EnsoPlus/SelectionListener/SelectionListener.cs`, `EnsoPlus/HandlerForSelection.cs`, and `EnsoPlus/SuggestionsCache.cs`. The corner-launcher subsystem provides keyboard listening, suggestion processing, and its own form: `EnsoPlus/CornerLauncher/KeysListener.cs`, `EnsoPlus/CornerLauncher/SuggestionsProcessor.cs`, and `EnsoPlus/CornerLauncher/FormCornerLauncher.cs`.

#### UI overlays and shared controls
The system is a classic Windows Forms desktop application, using overlay-like forms for launcher, menus, parameter entry, on-screen display, and notifications. Reusable UI projects include `ControlParameterInput/ParameterInput.cs`, `ControlMenu/ControlMenu.cs`, and `ControlOSD/OSD.cs`. Message display is handled separately through `EnsoPlus/MessageHandler/MessageHandler.cs` and `EnsoPlus/MessageHandler/FormMessageHandler.cs`.

#### Windows integration and companion processes
The repository depends on Windows APIs and desktop facilities: clipboard, registry, filesystem, process management, keyboard simulation, global user activity, and shortcut handling. Shared generated building blocks expose these boundaries in `CraftSynth.BuildingBlocks.Generated/CraftSynth.BuildingBlocks.WindowsNT.UserActivityHook.cs`, `CraftSynth.BuildingBlocks.Generated/CraftSynth.BuildingBlocks.IO.Clipboard.cs`, and `CraftSynth.BuildingBlocks.Generated/CraftSynth.BuildingBlocks.IO.Registry.cs`. Companion executables provide lifecycle/activity/shortcut support: `EnsoPlus.Guard/Program.cs`, `EnsoPlus.UserActivityBroadcaster/Program.cs`, and `EnsoPlus.LnkFileReader/Program.cs`. External integrations include DotRas for dial-up/RAS behavior and bundled 7-Zip at `EnsoPlus/Tools/7-zip/7z.exe`.

Main entry points: [`EnsoPlus/FormMain.cs`](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/FormMain.cs) (Main Launcher Form), [`EnsoPlus/CommandsProviders/CommandsManager/CommandsManager.cs`](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/CommandsProviders/CommandsManager/CommandsManager.cs) (Commands Manager), [`CraftSynth.BuildingBlocks.Generated/CraftSynth.BuildingBlocks.WindowsNT.UserActivityHook.cs`](https://github.com/f4cio/ensoplus/blob/master/CraftSynth.BuildingBlocks.Generated/CraftSynth.BuildingBlocks.WindowsNT.UserActivityHook.cs) (Windows Desktop APIs), [`EnsoPlus/SuggestionsCache.cs`](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/SuggestionsCache.cs) (Suggestions Cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launcher["Launcher Core"]
  node_program["Application Entry<br/>WinForms executable<br/>[Program.cs]"]
  node_main_form["Main Launcher Form<br/>WinForms surface<br/>[FormMain.cs]"]
  node_command_contract["Command Contract<br/>command model"]
  node_command_entity["Command Entities<br/>command data<br/>[Command.cs]"]
  node_extension_contract["Extension Boundary<br/>extension API<br/>[IEnsoExtension.cs]"]
  node_selection_listener["Selection Listener<br/>desktop context listener"]
  node_selection_handler["Selection Handler<br/>selection workflow"]
  node_suggestions_cache[("Suggestions Cache<br/>suggestion cache")]
  node_corner_launcher["Corner Launcher<br/>keyboard suggestion flow<br/>[KeysListener.cs]"]
end

subgraph group_providers["Commands &amp; Work Items"]
  node_commands_manager["Commands Manager<br/>command coordinator<br/>[CommandsManager.cs]"]
  node_opener["Opener Provider<br/>command provider<br/>[Opener.cs]"]
  node_web_searcher["Web Search Provider<br/>command provider<br/>[WebSearcher.cs]"]
  node_work_item_model["Work Item Entities<br/>searchable data model"]
  node_shortcuts["Shortcuts Provider<br/>work-item provider<br/>[Shortcuts.cs]"]
  node_history["Command History<br/>work-item provider<br/>[CommandsHistory.cs]"]
  node_clipboard["Clipboard Provider<br/>work-item provider<br/>[ClipboardText.cs]"]
end

subgraph group_ui["Desktop UI"]
  node_corner_form["Corner Launcher Form<br/>WinForms overlay"]
  node_shared_controls["Shared Overlay Controls<br/>WinForms controls<br/>[ParameterInput.cs]"]
  node_message_handler["Message Handler<br/>notification UI<br/>[MessageHandler.cs]"]
end

subgraph group_integration["Windows Integration"]
  node_windows_apis{{"Windows Desktop APIs<br/>platform integration"}}
  node_companion_processes["Companion Processes<br/>support executables<br/>[Program.cs]"]
  node_external_tools["External Tools<br/>bundled integration<br/>[7z.exe]"]
end

node_program -->|"starts"| node_main_form
node_main_form -->|"submits input"| node_commands_manager
node_main_form -->|"shows suggestions"| node_suggestions_cache
node_command_contract -->|"defines provider contract"| node_commands_manager
node_command_entity -->|"carries command data"| node_commands_manager
node_extension_contract -.->|"extends behavior"| node_commands_manager
node_commands_manager -->|"delegates open actions"| node_opener
node_commands_manager -->|"delegates search actions"| node_web_searcher
node_shortcuts -->|"supplies"| node_work_item_model
node_history -->|"supplies"| node_work_item_model
node_clipboard -->|"supplies"| node_work_item_model
node_work_item_model -->|"feeds searchable items"| node_suggestions_cache
node_selection_listener -->|"captures selection"| node_selection_handler
node_selection_handler -->|"injects context"| node_main_form
node_corner_launcher -->|"queries suggestions"| node_suggestions_cache
node_corner_launcher -->|"drives overlay"| node_corner_form
node_main_form -->|"uses"| node_shared_controls
node_main_form -->|"publishes messages"| node_message_handler
node_windows_apis -->|"provides activity hooks"| node_selection_listener
node_windows_apis -->|"provides clipboard access"| node_clipboard
node_companion_processes -.->|"supports desktop lifecycle"| node_windows_apis
node_opener -.->|"invokes tools"| node_external_tools

click node_program "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/Program.cs"
click node_main_form "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/FormMain.cs"
click node_command_contract "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/Entities/ICommandsProvider.cs"
click node_command_entity "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/Entities/Command.cs"
click node_extension_contract "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/Entities/Extension/IEnsoExtension.cs"
click node_commands_manager "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/CommandsProviders/CommandsManager/CommandsManager.cs"
click node_opener "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/CommandsProviders/Opener/Opener.cs"
click node_web_searcher "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/CommandsProviders/WebSearcher/WebSearcher.cs"
click node_shortcuts "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/WorkItemsProviders/Shortcuts/Shortcuts.cs"
click node_history "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/WorkItemsProviders/CommandsHistory/CommandsHistory.cs"
click node_clipboard "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/WorkItemsProviders/Clipboard/ClipboardText.cs"
click node_selection_listener "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/SelectionListener/SelectionListener.cs"
click node_selection_handler "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/HandlerForSelection.cs"
click node_suggestions_cache "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/SuggestionsCache.cs"
click node_corner_launcher "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/CornerLauncher/KeysListener.cs"
click node_corner_form "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/CornerLauncher/FormCornerLauncher.cs"
click node_shared_controls "https://github.com/f4cio/ensoplus/blob/master/ControlParameterInput/ParameterInput.cs"
click node_message_handler "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/MessageHandler/MessageHandler.cs"
click node_windows_apis "https://github.com/f4cio/ensoplus/blob/master/CraftSynth.BuildingBlocks.Generated/CraftSynth.BuildingBlocks.WindowsNT.UserActivityHook.cs"
click node_companion_processes "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus.Guard/Program.cs"
click node_external_tools "https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/Tools/7-zip/7z.exe"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_program,node_main_form,node_command_contract,node_command_entity,node_extension_contract,node_selection_listener,node_selection_handler,node_suggestions_cache,node_corner_launcher toneBlue
class node_commands_manager,node_opener,node_web_searcher,node_work_item_model,node_shortcuts,node_history,node_clipboard toneAmber
class node_corner_form,node_shared_controls,node_message_handler toneMint
class node_windows_apis,node_companion_processes,node_external_tools toneRose
```

## Components

### Launcher Core

- [Application Entry](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/Program.cs): WinForms executable · `EnsoPlus/Program.cs`
- [Main Launcher Form](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/FormMain.cs): WinForms surface · Accepts launcher input and presents results. · `EnsoPlus/FormMain.cs`
- [Command Contract](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/Entities/ICommandsProvider.cs): command model · `EnsoPlus/Entities/ICommandsProvider.cs`
- [Command Entities](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/Entities/Command.cs): command data · `EnsoPlus/Entities/Command.cs`
- [Extension Boundary](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/Entities/Extension/IEnsoExtension.cs): extension API · `EnsoPlus/Entities/Extension/IEnsoExtension.cs`
- [Selection Listener](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/SelectionListener/SelectionListener.cs): desktop context listener · `EnsoPlus/SelectionListener/SelectionListener.cs`
- [Selection Handler](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/HandlerForSelection.cs): selection workflow · `EnsoPlus/HandlerForSelection.cs`
- [Suggestions Cache](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/SuggestionsCache.cs): suggestion cache · `EnsoPlus/SuggestionsCache.cs`
- [Corner Launcher](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/CornerLauncher/KeysListener.cs): keyboard suggestion flow · Captures hotkeys and processes corner-launcher suggestions. · `EnsoPlus/CornerLauncher/KeysListener.cs`

### Commands & Work Items

- [Commands Manager](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/CommandsProviders/CommandsManager/CommandsManager.cs): command coordinator · Resolves input and delegates selected actions to providers. · `EnsoPlus/CommandsProviders/CommandsManager/CommandsManager.cs`
- [Opener Provider](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/CommandsProviders/Opener/Opener.cs): command provider · Opens files, processes, and related targets. · `EnsoPlus/CommandsProviders/Opener/Opener.cs`
- [Web Search Provider](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/CommandsProviders/WebSearcher/WebSearcher.cs): command provider · `EnsoPlus/CommandsProviders/WebSearcher/WebSearcher.cs`
- **Work Item Entities**: searchable data model
- [Shortcuts Provider](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/WorkItemsProviders/Shortcuts/Shortcuts.cs): work-item provider · `EnsoPlus/WorkItemsProviders/Shortcuts/Shortcuts.cs`
- [Command History](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/WorkItemsProviders/CommandsHistory/CommandsHistory.cs): work-item provider · `EnsoPlus/WorkItemsProviders/CommandsHistory/CommandsHistory.cs`
- [Clipboard Provider](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/WorkItemsProviders/Clipboard/ClipboardText.cs): work-item provider · `EnsoPlus/WorkItemsProviders/Clipboard/ClipboardText.cs`

### Desktop UI

- [Corner Launcher Form](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/CornerLauncher/FormCornerLauncher.cs): WinForms overlay · `EnsoPlus/CornerLauncher/FormCornerLauncher.cs`
- [Shared Overlay Controls](https://github.com/f4cio/ensoplus/blob/master/ControlParameterInput/ParameterInput.cs): WinForms controls · Reusable parameter input, menu, and OSD controls. · `ControlParameterInput/ParameterInput.cs`
- [Message Handler](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/MessageHandler/MessageHandler.cs): notification UI · `EnsoPlus/MessageHandler/MessageHandler.cs`

### Windows Integration

- [Windows Desktop APIs](https://github.com/f4cio/ensoplus/blob/master/CraftSynth.BuildingBlocks.Generated/CraftSynth.BuildingBlocks.WindowsNT.UserActivityHook.cs): platform integration · Provides user activity hooks, clipboard, and registry access. · `CraftSynth.BuildingBlocks.Generated/CraftSynth.BuildingBlocks.WindowsNT.UserActivityHook.cs`
- [Companion Processes](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus.Guard/Program.cs): support executables · Guard, activity broadcaster, and shortcut reader support launcher lifecycle. · `EnsoPlus.Guard/Program.cs`
- [External Tools](https://github.com/f4cio/ensoplus/blob/master/EnsoPlus/Tools/7-zip/7z.exe): bundled integration · Includes bundled 7-Zip and RAS integration. · `EnsoPlus/Tools/7-zip/7z.exe`

## Connections

- Application Entry → Main Launcher Form: starts
- Main Launcher Form → Commands Manager: submits input
- Main Launcher Form → Suggestions Cache: shows suggestions
- Command Contract → Commands Manager: defines provider contract
- Command Entities → Commands Manager: carries command data
- Extension Boundary → Commands Manager: extends behavior
- Commands Manager → Opener Provider: delegates open actions
- Commands Manager → Web Search Provider: delegates search actions
- Shortcuts Provider → Work Item Entities: supplies
- Command History → Work Item Entities: supplies
- Clipboard Provider → Work Item Entities: supplies
- Work Item Entities → Suggestions Cache: feeds searchable items
- Selection Listener → Selection Handler: captures selection
- Selection Handler → Main Launcher Form: injects context
- Corner Launcher → Suggestions Cache: queries suggestions
- Corner Launcher → Corner Launcher Form: drives overlay
- Main Launcher Form → Shared Overlay Controls: uses
- Main Launcher Form → Message Handler: publishes messages
- Windows Desktop APIs → Selection Listener: provides activity hooks
- Windows Desktop APIs → Clipboard Provider: provides clipboard access
- Companion Processes → Windows Desktop APIs: supports desktop lifecycle
- Opener Provider → External Tools: invokes tools