# jline/jline3 architecture

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

- Interactive diagram: https://gitdiagram.com/jline/jline3
- Repository: https://github.com/jline/jline3

## Overview

##### Project type and purpose
- JLine is an open-source, multi-module Java console library.
- Purpose: provide a portable, flexible console/terminal abstraction with line-editing, history, completion, syntax highlighting, styling, UI widgets, built-in commands, and remote shells (SSH/Telnet).

##### High-level module structure
- Core/low-level modules:
- **jline-terminal**: Terminal SPI, providers (Posix, Windows, exec).
- **jansi-core**, **terminal-jansi**, **terminal-jna**, **terminal-jni**, **terminal-ffm**, **native**: platform-specific native/Java bridges for PTYs, ANSI support.
- **curses**: high-level GUI abstraction on top of terminal.
- Mid-level modules:
- **jline-reader**: line-editor, parser, completers, history.
- High-level modules:
- **jline-console**: REPL engine, command registry, scripting support.
- **jline-console-ui**: interactive prompts, menus, checkboxes, lists.
- **jline-builtins**: built-in shell commands (nano, less, tmux, etc.) and configuration.
- **jline-remote-ssh**, **jline-remote-telnet**: SSH/Telnet server front-ends built on console and reader.
- Supporting modules:
- **groovy**: Groovy scripting integration.
- **demo**, **graal**: sample applications, Graal native-image demos.
- **website**: documentation site (Docusaurus).

##### Dependency relationships and data flow
- **Application** → uses JLine API.
- **jline-terminal** sits at the bottom (SPI for I/O).
- TerminalProviders (exec, native, jansi, jna, jni, ffm) loaded via Java ServiceLoader.
- **jline-reader** depends on jline-terminal (for raw input/output).
- **jline-console** depends on jline-reader + jline-terminal.
- **jline-console-ui** depends on jline-console + jline-style.
- **jline-builtins** depends on jline-console-ui + jline-reader.
- **jline-remote-ssh/telnet** depend on jline-console + jline-builtins (for shell commands).
- **curses** and **groovy** integrate at various levels (curses on terminal + UI; groovy as script engine in console).

##### Architectural patterns and principles
- Layered modular architecture: core → reader → console → UI/commands → remote.
- SPI/ServiceLoader for pluggable TerminalProviders.
- Builder patterns (TerminalBuilder, LineReaderBuilder) for configuration.
- Separation of concerns: I/O abstraction, line editing, parsing, UI, commands.
- Extensibility points: custom Completers, Highlighters, Widgets, Style sources, Script engines.

##### Elements
- Clear labels on each module/component (use full artifactId).
- Rectangles for core libraries/modules

##### Quick sketch of component grouping
┌──────────────────────────────────┐
│  Application (user code)        │
└─────────┬────────────────────────┘
│ uses public APIs
┌─────────▼─────────┐
│ jline-console-ui  │
└─────────┬─────────┘
│ builds on
┌─────────▼─────────┐    plugins
│ jline-console     │◀──────────────┐
└─────────┬─────────┘               │
│ uses reader             │
┌─────────▼─────────┐      ┌─────────▼─────────┐
│ jline-reader      │      │ groovy scripting  │
└─────────┬─────────┘      └───────────────────┘
│ uses terminal
┌─────────▼─────────┐      SPI/providers
│ jline-terminal    │◀────────────────────────┐
└───────────────────┘                         │
│      │      ┌────────────────────┐  │
│      └─────▶│ jansi, jna, jni,   │  │
│             │ ffm, native, exec  │  │
│             └────────────────────┘  │
│                                     │
└─────────────▶ curses/UI widgets────┘

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Application
    App["Application (User Code)"] 

    %% UI/Commands Layer
    UI["jline-console-ui"]:::ui
    Console["jline-console"]:::console
    Builtins["jline-builtins"]:::ui
    RemoteSSH["jline-remote-ssh"]:::ui
    RemoteTelnet["jline-remote-telnet"]:::ui

    %% Mid-Level Layer
    Style["jline-style"]:::reader
    Reader["jline-reader"]:::reader
    Groovy["groovy (Scripting Integration)"]:::ext

    %% Core Layer
    Terminal["jline-terminal"]:::core
    Providers["Terminal Providers"]:::ext
    JansiCore["jansi-core"]:::core
    TerminalJansi["terminal-jansi"]:::core
    TerminalJna["terminal-jna"]:::core
    TerminalJni["terminal-jni"]:::core
    TerminalFfm["terminal-ffm"]:::core
    NativeProv["native"]:::core
    Curses["curses (GUI Abstraction)"]:::ext

    %% Docs/Demos
    Demo["demo"]:::docs
    Graal["graal"]:::docs
    Website["website"]:::docs

    %% Dependencies
    App -->|"uses public APIs"| UI
    UI -->|"builds on"| Console
    UI -->|"uses style"| Style
    Console -->|"uses reader"| Reader
    Console -->|"SPI plugins"| Providers
    Console -->|"supports scripting"| Groovy
    Reader -->|"uses terminal"| Terminal
    Builtins -->|"depends on"| UI
    Builtins -->|"depends on"| Reader
    RemoteSSH -->|"depends on"| Console
    RemoteSSH -->|"uses commands"| Builtins
    RemoteTelnet -->|"depends on"| Console
    RemoteTelnet -->|"uses commands"| Builtins
    Terminal -->|"provides I/O SPI"| Providers
    Providers -->|"loaded via ServiceLoader"| Terminal
    Terminal -->|"integrates GUI"| Curses
    UI -->|"uses GUI widgets"| Curses

    %% Grouping Providers
    subgraph "Terminal Providers (SPI)" 
        direction TB
        JansiCore
        TerminalJansi
        TerminalJna
        TerminalJni
        TerminalFfm
        NativeProv
    end

    %% Docs/Demos Group
    subgraph "Samples & Docs"
        direction TB
        Demo
        Graal
        Website
    end

    %% Click Events
    click Terminal "https://github.com/jline/jline3/tree/master/terminal/"
    click JansiCore "https://github.com/jline/jline3/tree/master/jansi-core/"
    click TerminalJansi "https://github.com/jline/jline3/tree/master/terminal-jansi/"
    click TerminalJna "https://github.com/jline/jline3/tree/master/terminal-jna/"
    click TerminalJni "https://github.com/jline/jline3/tree/master/terminal-jni/"
    click TerminalFfm "https://github.com/jline/jline3/tree/master/terminal-ffm/"
    click NativeProv "https://github.com/jline/jline3/tree/master/native/"
    click Curses "https://github.com/jline/jline3/tree/master/curses/"
    click Reader "https://github.com/jline/jline3/tree/master/reader/"
    click Style "https://github.com/jline/jline3/tree/master/style/"
    click Console "https://github.com/jline/jline3/tree/master/console/"
    click UI "https://github.com/jline/jline3/tree/master/console-ui/"
    click Builtins "https://github.com/jline/jline3/tree/master/builtins/"
    click RemoteSSH "https://github.com/jline/jline3/tree/master/remote-ssh/"
    click RemoteTelnet "https://github.com/jline/jline3/tree/master/remote-telnet/"
    click Groovy "https://github.com/jline/jline3/tree/master/groovy/"
    click Demo "https://github.com/jline/jline3/tree/master/demo/"
    click Graal "https://github.com/jline/jline3/tree/master/graal/"
    click Website "https://github.com/jline/jline3/tree/master/website/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef reader fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef console fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef ui fill:#e2d6f3,stroke:#333,stroke-width:1px;
    classDef ext fill:#d1ecf1,stroke:#333,stroke-width:1px;
    classDef docs fill:#e2e3e5,stroke-dasharray: 5 5,stroke:#333,stroke-width:1px;
```
