# koteitan/koteiterm architecture

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

- Interactive diagram: https://gitdiagram.com/koteitan/koteiterm
- Repository: https://github.com/koteitan/koteiterm

## Overview

##### Project Type and Purpose
- This is a native Linux terminal emulator written in C, using X11/Xft for rendering.
- It includes an optional Windows-clipboard integration subproject (`winclip`).

##### File Structure
- Top-level: `src/` (core modules), `include/` (headers), `test/` (shell integration tests), `winclip/` (WSL/Win clipboard helper).
- Core modules in `src/`:
- `main.c` – program entry, main loop coordination
- `input.c` – keyboard & mouse event handling
- `pty.c` – pseudoterminal master/slave management
- `terminal.c` – VT100 escape‐sequence parser & terminal buffer
- `display.c` – X11 window management & rendering
- Build/deploy files: `Makefile`, `winclip/Makefile`.

##### Extract Key Architecture Notes from README
- stdin → input buffer → main loop → (Media Copy vs normal data) → PTY write → shell process → PTY read → VT100 parser → terminal buffer → (render or screenshot) → X11 window or stdout.
- External libs: X11, Xft, Fontconfig, Freetype, Imlib2, GIF.
- Optional: MinGW cross-compile for `winclip.exe`.

##### Main Components & Their Relationships
1. **CLI Frontend**
- Reads `stdin` (user input, piped commands)
- Presents command‐line flags
2. **Input Manager** (`input.c`)
- Handles keyboard/mouse events
- Dispatches to PTY master (key events) or selection logic
3. **Media Copy Detector** (`terminal.c` helper)
- Scans for ESC[5i/4i/4;0i sequences
- Branches to screenshot logic
4. **PTY Layer** (`pty.c`)
- PTY Master FD write: sends input to shell
- PTY Master FD read: reads shell output
5. **Shell Process** (external `bash`/`zsh`)
6. **VT100 Parser & Terminal Buffer** (`terminal.c`)
- Parses escape sequences, updates `g_terminal.cells[]`
- Maintains scrollback buffer
8. **Screenshot Handler**
- Captures buffer on ESC[5i → stores in screenshot buffer
- Emits on ESC[4i to `stdout`
9. **WinClip Bridge** (`winclip/winclip.c`)
- Invoked in WSL for Windows clipboard sync

- X11
- Xft / Fontconfig / Freetype
- Imlib2 / GIF libs
- Shell binary

##### Architectural Patterns & Design Principles
- **Modular C architecture**: each subsystem in its own module / header
- **Event-driven loop**: MainLoop polls stdin, PTY, X events
- **Separation of concerns**: input vs parsing vs rendering vs I/O
- **Extensibility points**: adding new VT100 sequences, custom cursors, additional escape commands

##### Detailed Elements
- Input/Output
- Core Parser/Buffer
- Rendering
- External processes & libs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input and Frontend
    subgraph "Input / Frontend"
        direction TB
        stdin["stdin"]:::io
        CLI["CLI Frontend"]:::core
        Input["Input Manager"]:::core
        Mouse["Mouse Events"]:::io
    end

    %% Core Processing
    subgraph "Core Processing"
        direction TB
        PTYW["PTY Layer Write"]:::core
        Shell["Shell Process"]:::process
        PTYR["PTY Layer Read"]:::core
        VT["VT100 Parser & Terminal Buffer"]:::core
        ScreenshotHandler["Screenshot Handler"]:::core
        Selection["Selection Logic"]:::core
    end

    %% Rendering
    subgraph "Rendering"
        direction TB
        Render["Rendering Engine"]:::core
        X11Win["X11 Window"]:::external
    end

    %% I/O Endpoints
    subgraph "I/O & Clipboard"
        direction TB
        stdout["stdout"]:::io
        Clipboard["X11 Clipboard"]:::external
        WinClip["WinClip Bridge"]:::process
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        X11Lib["X11"]:::external
        XftLib["Xft/Fontconfig/Freetype"]:::external
        ImgLib["Imlib2/GIF"]:::external
    end

    %% Data Flows
    stdin -->|"user input"| CLI
    CLI -->|"parsed flags & input"| Input
    Mouse -->|"mouse events"| Input
    Input -->|"write input"| PTYW
    PTYW -->|writes to| Shell
    Shell -->|output| PTYR
    PTYR -->|data| VT
    VT -->|update buffer| VT
    VT -->|render data| Render
    Render -->|draw| X11Win
    VT -->|screenshot seq| ScreenshotHandler
    ScreenshotHandler -->|image data| stdout
    Selection -->|copy text| Clipboard
    Input -->|selection trigger| Selection
    WinClip -.->|WSL clipboard sync| Clipboard

    %% External Dependencies usage
    Render --> X11Lib
    Render --> XftLib
    Render --> ImgLib

    %% Click Events
    click CLI "https://github.com/koteitan/koteiterm/blob/main/src/main.c"
    click Input "https://github.com/koteitan/koteiterm/blob/main/src/input.c"
    click PTYW "https://github.com/koteitan/koteiterm/blob/main/src/pty.c"
    click PTYR "https://github.com/koteitan/koteiterm/blob/main/src/pty.c"
    click VT "https://github.com/koteitan/koteiterm/blob/main/src/terminal.c"
    click ScreenshotHandler "https://github.com/koteitan/koteiterm/blob/main/src/terminal.c"
    click Render "https://github.com/koteitan/koteiterm/blob/main/src/display.c"
    click WinClip "https://github.com/koteitan/koteiterm/blob/main/winclip/winclip.c"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef external fill:#ABEBC6,stroke:#196F3D,color:#145A32;
    classDef process fill:#F9E79F,stroke:#B7950B,color:#7D6608;
    classDef io fill:#F5B7B1,stroke:#922B21,color:#641E16;
```
