# atm1020/tuilaunch architecture

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

- Interactive diagram: https://gitdiagram.com/atm1020/tuilaunch
- Repository: https://github.com/atm1020/tuilaunch

## Overview

##### Project Type and Purpose
- This is an **IntelliJ Platform Plugin** (“TUILaunch”) that integrates with JetBrains IDEs to launch terminal‐based TUI applications (e.g. lazygit) inside the IDE’s built‐in terminal.

##### File Structure
- Top-level build & config: gradle files, GitHub workflows, plugin.xml under src/main/resources/META-INF.
- Code packages:
- **action** (DynamicTuiAction, SelectAppTuiAction)
- **listeners** (TerminalContextManagerListener)
- **model** (TuiAppConfig, TuiAppTableModel)
- **services** (TuiAppLaunchService, TuiLauncherSettings)
- **ui** (TuiLauncherConfiguration)
- Tests under src/test.
- Resources: plugin.xml declares extensions (actions, settings page).

##### Readme Insights
- Describes: settings UI, how actions are generated, how TUI apps launch in the terminal, lifecycle behaviors (auto-exit), limitations.

##### Main Components & Their Relationships
a. **IDE Host (IntelliJ Platform)**
‑ Provides Extension Points: Actions, SettingsConfigurable, StartupActivity, Terminal ToolWindow API.

b. **Plugin Entry Points**
‑ **plugin.xml** – registers:
- StartupActivity (to initialize plugin)
- Actions (dynamic action IDs)
- Settings page.

c. **StartupActivity**
‑ On IDE launch, reads saved app configs and registers DynamicTuiAction for each.

d. **Settings UI (TuiLauncherConfiguration)**
‑ Presents a table (TuiAppTableModel) for CRUD on TuiAppConfig
‑ Persists into**TuiLauncherSettings** service.

e. **Model & Storage**
‑ **TuiAppConfig** – holds command, display name, tool-window preferences
‑ **TuiLauncherSettings** – persistent service (IDE’s PersistentStateComponent)

f. **Actions (DynamicTuiAction, SelectAppTuiAction)**
‑ Triggered via menu/shortcut/IdeaVim
‑ Delegate to **TuiAppLaunchService**

g. **TuiAppLaunchService**
‑ Uses IntelliJ’s Terminal ToolWindow API to open a new terminal session
‑ Executes `${command}; exit` in that terminal
‑ Hooks into **TerminalContextManagerListener** to manage focus/cleanup

h. **Listener (TerminalContextManagerListener)**
‑ Observes terminal focus changes
‑ Ensures only one TUI session at a time, closes previous on new launch

i. **External Process**
‑ The TUI application (e.g. lazygit) launched inside the IDE’s terminal

##### Architectural Patterns & Principles
- **Extension-Point Pattern**: plugin.xml + StartupActivity + Configurable + Action EPs
- **MVC-ish for Settings**: UI (Configurable) ↔ Model (TuiAppTableModel) ↔ Service (TuiLauncherSettings)
- **Service Locator**: use IntelliJ’s service framework for persistence and launch service
- **Observer**: TerminalContextManagerListener observes terminal events

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% IDE Platform & APIs
    subgraph "IDE Platform & APIs"
        direction TB
        IDE["IntelliJ Platform"]:::ide
        EP["Extension Points"]:::ide
        TTAPI["Terminal ToolWindow API"]:::ide
    end

    %% Plugin Core
    subgraph "Plugin Core"
        direction TB
        PM["Plugin Manifest<br/>(plugin.xml)"]:::plugin
        SA["StartupActivity"]:::plugin
        SU["Settings UI<br/>(TuiLauncherConfiguration)"]:::plugin
        TM["TuiAppTableModel"]:::plugin
        TC["TuiAppConfig"]:::plugin
        SL["TuiLauncherSettings"]:::storage
        DA["DynamicTuiAction"]:::plugin
        SA2["SelectAppTuiAction"]:::plugin
        LS["TuiAppLaunchService"]:::plugin
        LN["TerminalContextManagerListener"]:::plugin
        LB["Localization Bundle"]:::plugin
        BT["Integration Tests"]:::plugin
        BC["Build & Configuration"]:::plugin
    end

    %% External
    EXT["External TUI App"]:::external

    %% Connections
    IDE --> EP
    EP --> SA
    SA -->|"reads settings"| SL
    SA -->|"registers actions"| DA
    SA -->|"registers actions"| SA2
    SU -->|"uses model"| TM
    SU -->|"edits config"| TC
    SU -->|"persists"| SL
    SL -->|"stores config"| TC
    DA -->|"executeCommand()"| LS
    SA2 -->|"executeCommand()"| LS
    LS -->|"open terminal"| TTAPI
    TTAPI -->|"launches command"| EXT
    LS -->|"hooks listener"| LN
    LN -->|"stateChanged()"| TTAPI

    %% Click Events
    click PM "https://github.com/atm1020/tuilaunch/blob/main/src/main/resources/META-INF/plugin.xml"
    click SA "https://github.com/atm1020/tuilaunch/blob/main/src/main/kotlin/com/github/atm1020/tuilaunch/StartupActivity.kt"
    click SU "https://github.com/atm1020/tuilaunch/blob/main/src/main/kotlin/com/github/atm1020/tuilaunch/ui/TuiLauncherConfiguration.kt"
    click TC "https://github.com/atm1020/tuilaunch/blob/main/src/main/kotlin/com/github/atm1020/tuilaunch/model/TuiAppConfig.kt"
    click TM "https://github.com/atm1020/tuilaunch/blob/main/src/main/kotlin/com/github/atm1020/tuilaunch/model/TuiAppTableModel.kt"
    click SL "https://github.com/atm1020/tuilaunch/blob/main/src/main/kotlin/com/github/atm1020/tuilaunch/services/TuiLaucherSettings.kt"
    click DA "https://github.com/atm1020/tuilaunch/blob/main/src/main/kotlin/com/github/atm1020/tuilaunch/action/DynamicTuiAction.kt"
    click SA2 "https://github.com/atm1020/tuilaunch/blob/main/src/main/kotlin/com/github/atm1020/tuilaunch/action/SelectAppTuiAction.kt"
    click LS "https://github.com/atm1020/tuilaunch/blob/main/src/main/kotlin/com/github/atm1020/tuilaunch/services/TuiAppLaunchService.kt"
    click LN "https://github.com/atm1020/tuilaunch/blob/main/src/main/kotlin/com/github/atm1020/tuilaunch/listeners/TerminalContextManagerListener.kt"
    click LB "https://github.com/atm1020/tuilaunch/blob/main/src/main/kotlin/com/github/atm1020/tuilaunch/MyBundle.kt"
    click LB "https://github.com/atm1020/tuilaunch/blob/main/src/main/resources/messages/MyBundle.properties"
    click BT "https://github.com/atm1020/tuilaunch/blob/main/src/test/kotlin/com/github/atm1020/tuilaunch/MyPluginTest.kt"
    click BC "https://github.com/atm1020/tuilaunch/blob/main/build.gradle.kts"
    click BC "https://github.com/atm1020/tuilaunch/blob/main/settings.gradle.kts"
    click BC "https://github.com/atm1020/tuilaunch/tree/main/.github/workflows/"

    %% Styles
    classDef ide fill:#b6d7a8,stroke:#38761d,color:#000
    classDef plugin fill:#a4c2f4,stroke:#3d85c6,color:#000
    classDef external fill:#f9cb9c,stroke:#e69138,color:#000
    classDef storage fill:#ffe599,stroke:#b45f06,color:#000
    class IDE,EP,TTAPI ide
    class PM,SA,SU,TM,TC,DA,SA2,LS,LN,LB,BT,BC plugin
    class SL storage
    class EXT external
```
