# jroimartin/gocui architecture

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

- Interactive diagram: https://gitdiagram.com/jroimartin/gocui
- Repository: https://github.com/jroimartin/gocui

## Overview

##### Project Type & Purpose
- GOCUI is a Go library (console UI toolkit) that provides:
- A main event loop (GUI core)
- View/window abstractions implementing io.ReadWriter
- Key/mouse input handling
- Runtime-safe modification of the GUI
- Layout and widget support
- It is *not* a standalone application but a reusable framework for building TUI (text-based UI) apps.

##### File Structure & Key Modules
- gui.go: Core GUI struct, main loop, concurrency-safe state.
- view.go: View abstraction, buffer management, overlapping.
- keybinding.go: Global & per-view key/mouse event registration & dispatch.
- edit.go / attribute.go / escape.go: Text editing & ANSI/terminal attribute utilities.
- doc.go: Package documentation & public API overview.
- _examples/: Sample programs showing how to use the library.

##### Extract Architectural Insights from README
- Minimalist API => slim core with clear extension points.
- Views implement io.ReadWriter => underlying buffer model.
- Concurrent-safe runtime modifications => internal locking or channel-based event queue.

##### Main Components
a. External Entities
- Application (user’s Go binary)
- Terminal / OS
b. GOCUI Core Modules
1. Gui Manager (gui.go)
2. Event Loop & Dispatcher
3. Input Handler (keybinding.go + mouse)
4. View Manager (view.go)
5. Layout Manager / ManagerFunc (user-provided callback)
6. Rendering Engine (attributes, escape.go)
7. Widget & Helpers (edit.go, attribute.go)
c. Data Stores / State
- View buffers & z-order list
- Keybinding & event maps
d. Concurrency Controls
- Mutexes or channels inside Gui Manager

##### Relationships & Data Flows
- Application → calls GOCUI API (NewGui, SetKeybinding, SetManagerFunc, MainLoop)
- Event Loop polls OS/terminal → raw input
- Input Handler normalizes events → dispatch to keybinding callbacks
- ManagerFunc (layout) invoked → user code modifies Views
- View Manager updates internal view buffers & positions
- Rendering Engine draws buffers → writes ANSI escapes to Terminal
- Terminal renders text windows to screen
- GUI Core ensures thread-safe modifications (locks/channels)

##### Architectural Patterns & Principles
- Event-loop pattern (reactive GUI)
- MVC-lite: Views + Controller (callbacks)
- Dependency-inversion: user supplies layout/controller via callbacks
- Concurrency-safe shared state

##### Relevant Technologies & Libraries
- Go standard library (io.ReadWriter, sync primitives)
- Underlying terminal driver (e.g., termbox-go)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    Application["Application"]:::external
    Terminal[/Terminal\/OS/]:::io

    %% Core Modules
    GuiManager["Gui Manager"]:::core
    EventLoop["Event Loop & Dispatcher"]:::core
    InputHandler["Input Handler"]:::core
    ViewManager["View Manager"]:::core
    RenderingEngine{"Rendering Engine"}:::core
    AttrUtility["Text Attributes Utility"]:::core
    EditHelpers["Text Editing Helpers"]:::core
    PackageDoc["Public API & Documentation"]:::core

    %% User Callbacks
    LayoutManager[/"Layout Manager (ManagerFunc)"/]:::user

    %% Data Stores
    subgraph "Data Stores"
        ViewBuffers[(View Buffers & Z-Order)]:::data
        KeyBindings[(Keybinding Map)]:::data
    end

    %% Examples
    Examples("Sample Applications (_examples/)"):::examples

    %% Connections
    Application -->|"NewGui, SetKeybinding, SetManagerFunc, MainLoop"| GuiManager
    GuiManager --> EventLoop
    EventLoop -->|"poll input"| Terminal
    Terminal -->|"raw events"| InputHandler
    InputHandler --> KeyBindings
    InputHandler -->|"dispatch events"| LayoutManager
    LayoutManager -->|"modify views"| ViewManager
    ViewManager --> ViewBuffers
    ViewBuffers --> RenderingEngine
    AttrUtility --> RenderingEngine
    EditHelpers --> RenderingEngine
    RenderingEngine -->|"ANSI escapes"| Terminal
    Examples -->|"imports API"| GuiManager
    PackageDoc -.-> Application

    %% Click Events
    click GuiManager "https://github.com/jroimartin/gocui/blob/master/gui.go"
    click EventLoop "https://github.com/jroimartin/gocui/blob/master/gui.go"
    click InputHandler "https://github.com/jroimartin/gocui/blob/master/keybinding.go"
    click ViewManager "https://github.com/jroimartin/gocui/blob/master/view.go"
    click LayoutManager "https://github.com/jroimartin/gocui/blob/master/doc.go"
    click RenderingEngine "https://github.com/jroimartin/gocui/blob/master/escape.go"
    click AttrUtility "https://github.com/jroimartin/gocui/blob/master/attribute.go"
    click EditHelpers "https://github.com/jroimartin/gocui/blob/master/edit.go"
    click PackageDoc "https://github.com/jroimartin/gocui/blob/master/doc.go"
    click Examples "https://github.com/jroimartin/gocui/tree/master/_examples/"

    %% Styles
    classDef external fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef io fill:#D5DBDB,stroke:#616A6B,color:#1C2833;
    classDef core fill:#ABEBC6,stroke:#1D8348,color:#145A32;
    classDef data fill:#F9E79F,stroke:#B9770E,color:#7D6608;
    classDef user fill:#F5B7B1,stroke:#C0392B,color:#641E16;
    classDef examples fill:#FAD7A0,stroke:#B9770E,color:#6E2C00;
```
