# dnpp73/terminal architecture

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

- Interactive diagram: https://gitdiagram.com/dnpp73/terminal
- Repository: https://github.com/dnpp73/terminal

## Overview

##### Main Components
- Terminal Emulator Library: This is the core of the project. Split it into two conceptual parts:
– Public API: Located in Sources/Terminal/Public (e.g., classes like TerminalView, TerminalClearEvent, TerminalSize, etc.) that clients of the library use.
– Internal Mechanics: Found under Sources/Terminal/Internal (e.g., Character+Control, HtermWebView, debugLog, UIView+EdgeConstraints, etc.). This part handles the internal logic like processing keystrokes, managing web view interactions, and bridging to hterm resources.
- Resources: The Resources subdirectory within Sources/Terminal includes essential assets (hterm.css, hterm.html, hterm_all.js, and hterm_bridge.js) that enable the terminal emulation in the WKWebView.
- Example Application: The Example directory contains an Xcode project which provides sample view controllers (e.g., TerminalViewController, SSHTerminalViewController) and additional supporting UI components (e.g., InputAccessoryView and KeyboardNotification) that demonstrate how to use the Terminal library.
- Build & Configuration Scripts: Files like the swiftlint.yml, Cartfile, and build scripts (bin/build_hterm.sh, for instance) show how to maintain coding standards and automate build tasks.

##### Out the Relationships and Interactions
- The Example App serves as the front end to showcase the Terminal library. In it, the user interacts with the Terminal emulator via UIKit components; these interact with the TerminalViewController.
- TerminalViewController (and related controllers like SSHTerminalViewController) instantiate and use the TerminalView (provided by the library) to display terminal output.
- The TerminalView internally uses a WKWebView to load the hterm-based interface (using assets from the Resources folder). There is a JavaScript bridge (hterm_bridge.js) to communicate between Swift/Objective-C code and the web view’s rendering engine.
- Additional utility modules (such as InputAccessoryView, KeyboardNotification, and Util components) support the handling of user input (hardware keyboard, Interface Builder UI) and event processing.
- Dependencies and integrations (like Carthage and Swift Package Manager compatibility) are indicated in the README, and these play a key role during the build and dependency resolution phases.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project divides responsibilities between a reusable Terminal library and a demonstration Example app, allowing for clear separation between core terminal functionality and sample application UI concerns.
- Modularity: Using distinct directories for Public and Internal code in Sources/Terminal makes it easier to manage the API boundary, while utility functions and view controllers are separated into their own directories.
- Bridge Pattern: The integration of WKWebView with hterm.js via JavaScript bridging demonstrates a clear separation of platform-specific UI (iOS) and the cross-platform terminal emulation logic.
- MVC (or similar iOS design philosophy): The controllers in the Example app (ViewControllers) manage the user interface along with the terminal logic from the library.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Configuration
    subgraph "Build & Configuration"
        BS("Build Script"):::config
        CS("Carthage Script"):::config
        LC("Lint Configuration"):::config
        PC("Project Config"):::config
    end

    %% Terminal Emulator Library
    subgraph "Terminal Emulator Library"
        PA("Public API"):::libPublic
        IM("Internal Mechanics"):::libInternal
        RA("Resource Assets"):::libResource
    end

    %% Example Application
    subgraph "Example Application"
        MA("Main App Code"):::app
        VC("ViewControllers"):::app
        IA("InputAccessoryView"):::app
        KN("KeyboardNotification"):::app
        UT("Util"):::app
    end

    %% iOS Platform
    subgraph "iOS Platform"
        UI("UIKit"):::platform
        WV("WKWebView"):::platform
    end

    %% Connections from Build & Config to Terminal Library
    BS -->|"build"| PA
    CS -->|"build"| PA
    LC -->|"lint"| PA
    PC -->|"config"| PA

    %% Connections within Example Application to Terminal Library
    MA -->|"integrates"| PA
    VC -->|"instantiates"| PA
    MA -->|"contains"| VC
    IA -->|"supports"| MA
    KN -->|"supports"| MA
    UT -->|"supports"| MA

    %% Connections from Terminal Library to iOS Platform
    PA -->|"renders"| WV
    IM -->|"processes"| WV
    RA -->|"loads"| WV
    MA -->|"uses"| UI
    VC -->|"displays"| UI

    %% Styling Classes
    classDef config fill:#ffcc00,stroke:#333,stroke-width:2px,color:#000;
    classDef libPublic fill:#99ccff,stroke:#333,stroke-width:2px,color:#000;
    classDef libInternal fill:#66ccff,stroke:#333,stroke-width:2px,color:#000;
    classDef libResource fill:#33bbff,stroke:#333,stroke-width:2px,color:#000;
    classDef app fill:#ff9999,stroke:#333,stroke-width:2px,color:#000;
    classDef platform fill:#ccffcc,stroke:#333,stroke-width:2px,color:#000;

    %% Click Events for Component Mapping
    click PA "https://github.com/dnpp73/terminal/tree/master/Sources/Terminal/Public"
    click IM "https://github.com/dnpp73/terminal/tree/master/Sources/Terminal/Internal"
    click RA "https://github.com/dnpp73/terminal/tree/master/Sources/Terminal/Resources"
    click MA "https://github.com/dnpp73/terminal/tree/master/Example/TerminalExample"
    click VC "https://github.com/dnpp73/terminal/tree/master/Example/TerminalExample/ViewController"
    click IA "https://github.com/dnpp73/terminal/tree/master/Example/TerminalExample/InputAccessoryView"
    click KN "https://github.com/dnpp73/terminal/tree/master/Example/TerminalExample/KeyboardNotification"
    click UT "https://github.com/dnpp73/terminal/tree/master/Example/TerminalExample/Util"
    click BS "https://github.com/dnpp73/terminal/blob/master/bin/build_hterm.sh"
    click CS "https://github.com/dnpp73/terminal/blob/master/Example/bin/carthage.sh"
    click LC "https://github.com/dnpp73/terminal/blob/master/.swiftlint.yml"
    click PC "https://github.com/dnpp73/terminal/blob/master/Package.swift"
```
