# mediar-ai/terminator architecture

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

- Interactive diagram: https://gitdiagram.com/mediar-ai/terminator
- Repository: https://github.com/mediar-ai/terminator

## Overview

##### Project type and purpose
- From the README and file tree, **terminator** is an AI-first, cross-platform UI-automation **library + server** written in Rust, with language-specific SDKs (TypeScript and Python) and various example clients. Its purpose is to let upstream clients (web apps, Python scripts, Rust programs) drive native GUI apps on Windows/macOS via a server using OS-level accessibility APIs.

##### File structure
- **Top-level Rust core**
- Cargo.toml, src/lib.rs, src/element.rs, src/locator.rs, src/selector.rs, src/utils.rs, src/errors.rs, src/tests.rs
- src/platforms/{windows.rs, macos.rs, linux.rs, tree_search.rs, mod.rs}
- **Server binaries & examples**
- setup_windows.ps1 → installs prebuilt server.exe
- examples/server.rs, example .exe under server_release/ (built via build-release.yml)
- **Language SDKs (clients)**
- ts-sdk/ (TypeScript client wrapper, package.json, src/index.ts)
- python-sdk/desktop_use (Python client wrapper, client.py, models.py, exceptions.py)
- **MCP CLI tool**
- mcp/ (TypeScript CLI “terminator cli” for “Vibe Work using MCP”)
- **Web and script examples**
- examples/hello-world (Next.js app calling ts-sdk through API routes)
- examples/pdf-to-form (Node example showing AI + terminator integration)
- examples/*.rs, examples/*.py (standalone Rust/Python demos)

##### README for additional insights
- Describes a **client–server architecture**: you build/run a server (server.exe or macOS binary), then you run client code (Rust example, TS SDK, Python SDK) that connects to it.
- Mentions **OS accessibility APIs** (uiautomation-rs on Windows, AppKit on macOS) as underlying dependencies.

a. **Core Terminator Engine** (Rust lib & server)
- **Platform Modules**: windows.rs, macos.rs, linux.rs, tree_search.rs
- **Core Logic**: element.rs, selector.rs, locator.rs, utils.rs
- **Server Layer**: server.rs (accepts incoming RPC/HTTP/WebSocket requests)
b. **Communication Layer**
- **Protocol**: JSON-RPC or HTTP API over localhost (port X)
- **Serialization**: arguments & return values (element handles, metadata)
c. **Language SDKs**
- **TypeScript SDK** (ts-sdk/src/index.ts): exposes a Playwright-like API, wraps HTTP calls to server.
- **Python SDK** (python-sdk/desktop_use/client.py): similar wrapper in Python.
d. **Client Applications**
- **Web Example**: examples/hello-world (Next.js + API routes + ts-sdk)
- **Node Example**: examples/pdf-to-form (Node.js script + ts-sdk)
- **Rust/Python Examples**: examples/simple.rs, examples/client_example.py
e. **External Dependencies & Debugging Tools**
- OS Accessibility APIs (uiautomation-rs on Windows, NSAccessibility on macOS)
- Dev tools: Accessibility Insights, FlaUInspect

##### Architectural patterns & design principles
- **Modular Platform Abstraction**: each OS lives in its own module under src/platforms.
- **Server–Client Separation**: heavy native automation logic runs in a single server process; SDKs remain thin clients.
- **Language-agnostic API**: JSON-RPC/HTTP boundaries let you support any client language.
- **Extensibility Points**: new platform implementations, new SDKs, new client examples.

##### Diagramming details
- Client → SDK → Server API → Core Engine → OS Accessibility API
- Core Engine → Platform Module
- **Green** for Rust native components (core library & server)
- **Blue** for SDKs (ts-sdk, python-sdk)
- **Orange** for clients (examples/**)
- **Gray** for external systems (OS APIs, debugging tools)
- **Ports/Protocols**: annotate “HTTP/JSON-RPC over localhost:port” on the boundary between SDK and server.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Terminator Server
    subgraph "Terminator Server" 
        direction TB
        ServerAPI["Server API Layer\n(HTTP/JSON-RPC)"]:::rust
        subgraph "Core Logic"
            direction TB
            Ele["element.rs"]:::rust
            Loc["locator.rs"]:::rust
            Sel["selector.rs"]:::rust
            Utils["utils.rs"]:::rust
            Err["errors.rs"]:::rust
            Tests["tests.rs"]:::rust
        end
        subgraph "Platform Modules"
            direction TB
            Mod["mod.rs"]:::rust
            WinPM["windows.rs"]:::rust
            MacPM["macos.rs"]:::rust
            LinPM["linux.rs"]:::rust
            TreePM["tree_search.rs"]:::rust
        end
        subgraph "Server Layer"
            direction TB
            ServerEntrypoint["examples/server.rs"]:::rust
            SetupScript["setup_windows.ps1"]:::rust
            BuildPipeline["build-release.yml"]:::rust
        end
    end

    %% SDKs
    subgraph "Language SDKs"
        direction TB
        subgraph "TypeScript SDK" 
            direction TB
            TSPkg["package.json"]:::sdk
            TSIndex["src/index.ts"]:::sdk
            TSConfig["tsconfig.json"]:::sdk
        end
        subgraph "Python SDK"
            direction TB
            PyProject["pyproject.toml"]:::sdk
            PyInit["__init__.py"]:::sdk
            PyClient["client.py"]:::sdk
            PyModels["models.py"]:::sdk
            PyExc["exceptions.py"]:::sdk
        end
    end

    %% MCP CLI
    subgraph "MCP CLI Tool"
        direction TB
        MCPPkg["package.json"]:::sdk
        MCPIndex["src/index.ts"]:::sdk
        MCPTerm["src/terminator.ts"]:::sdk
        MCPConfig["tsconfig.json"]:::sdk
    end

    %% Clients
    subgraph "Client Applications"
        direction TB
        subgraph "Web Example"
            direction TB
            WebPkg["package.json"]:::client
            NextCfg["next.config.ts"]:::client
            ApiRoutes["src/app/api"]:::client
            WebSDK["src/lib/sdk.ts"]:::client
        end
        subgraph "Node.js Example"
            direction TB
            NodePkg["package.json"]:::client
            NodeIndex["src/index.ts"]:::client
        end
        subgraph "Rust Examples"
            direction TB
            RustSimple["examples/simple.rs"]:::client
            RustButtonC["button/Cargo.toml"]:::client
            RustButtonSrc["button/src/main.rs"]:::client
            RustWinAuto["examples/win_automation.rs"]:::client
        end
        subgraph "Python Example"
            direction TB
            PyClientEx["examples/client_example.py"]:::client
            PyNotepad["examples/notepad.py"]:::client
        end
    end

    %% External OS APIs and Tools
    subgraph "External Dependencies"
        direction TB
        WinAPI["UIAutomation (Windows)"]:::external
        MacAPI["NSAccessibility (macOS)"]:::external
        DebugTools["Accessibility Insights / FlaUInspect"]:::external
    end

    %% Connections
    WebSDK -->|uses SDK| TSPkg
    ApiRoutes -->|calls| TSPkg
    NodeIndex -->|uses SDK| TSPkg
    RustSimple -->|direct RPC| ServerAPI
    RustButtonSrc -->|direct RPC| ServerAPI
    RustWinAuto -->|direct RPC| ServerAPI
    PyClientEx -->|uses SDK| PyClient
    PyNotepad -->|uses SDK| PyClient

    TSPkg -->|HTTP/JSON-RPC| ServerAPI
    PyClient -->|HTTP/JSON-RPC| ServerAPI
    MCPTerm -->|HTTP/JSON-RPC| ServerAPI

    ServerAPI -->|invokes| Ele
    ServerAPI -->|invokes| Loc
    ServerAPI -->|invokes| Sel
    ServerAPI -->|invokes| Utils
    ServerAPI -->|invokes| Err
    ServerAPI -->|runs tests| Tests

    ServerAPI -->|calls| Mod
    ServerAPI -->|calls| WinPM
    ServerAPI -->|calls| MacPM
    ServerAPI -->|calls| LinPM
    ServerAPI -->|calls| TreePM

    WinPM -->|via| WinAPI
    MacPM -->|via| MacAPI

    %% Click Events
    click Ele "https://github.com/mediar-ai/terminator/blob/main/src/element.rs"
    click Loc "https://github.com/mediar-ai/terminator/blob/main/src/locator.rs"
    click Sel "https://github.com/mediar-ai/terminator/blob/main/src/selector.rs"
    click Utils "https://github.com/mediar-ai/terminator/blob/main/src/utils.rs"
    click Err "https://github.com/mediar-ai/terminator/blob/main/src/errors.rs"
    click Tests "https://github.com/mediar-ai/terminator/blob/main/src/tests.rs"

    click Mod "https://github.com/mediar-ai/terminator/blob/main/src/platforms/mod.rs"
    click WinPM "https://github.com/mediar-ai/terminator/blob/main/src/platforms/windows.rs"
    click MacPM "https://github.com/mediar-ai/terminator/blob/main/src/platforms/macos.rs"
    click LinPM "https://github.com/mediar-ai/terminator/blob/main/src/platforms/linux.rs"
    click TreePM "https://github.com/mediar-ai/terminator/blob/main/src/platforms/tree_search.rs"

    click ServerEntrypoint "https://github.com/mediar-ai/terminator/blob/main/examples/server.rs"
    click SetupScript "https://github.com/mediar-ai/terminator/blob/main/setup_windows.ps1"
    click BuildPipeline "https://github.com/mediar-ai/terminator/blob/main/.github/workflows/build-release.yml"

    click TSPkg "https://github.com/mediar-ai/terminator/blob/main/ts-sdk/package.json"
    click TSIndex "https://github.com/mediar-ai/terminator/blob/main/ts-sdk/src/index.ts"
    click TSConfig "https://github.com/mediar-ai/terminator/blob/main/ts-sdk/tsconfig.json"

    click PyProject "https://github.com/mediar-ai/terminator/blob/main/python-sdk/pyproject.toml"
    click PyInit "https://github.com/mediar-ai/terminator/blob/main/python-sdk/desktop_use/__init__.py"
    click PyClient "https://github.com/mediar-ai/terminator/blob/main/python-sdk/desktop_use/client.py"
    click PyModels "https://github.com/mediar-ai/terminator/blob/main/python-sdk/desktop_use/models.py"
    click PyExc "https://github.com/mediar-ai/terminator/blob/main/python-sdk/desktop_use/exceptions.py"

    click MCPPkg "https://github.com/mediar-ai/terminator/blob/main/mcp/package.json"
    click MCPIndex "https://github.com/mediar-ai/terminator/blob/main/mcp/src/index.ts"
    click MCPTerm "https://github.com/mediar-ai/terminator/blob/main/mcp/src/terminator.ts"
    click MCPConfig "https://github.com/mediar-ai/terminator/blob/main/mcp/tsconfig.json"

    click WebPkg "https://github.com/mediar-ai/terminator/blob/main/examples/hello-world/package.json"
    click NextCfg "https://github.com/mediar-ai/terminator/blob/main/examples/hello-world/next.config.ts"
    click ApiRoutes "https://github.com/mediar-ai/terminator/tree/main/examples/hello-world/src/app/api"
    click WebSDK "https://github.com/mediar-ai/terminator/blob/main/examples/hello-world/src/lib/sdk.ts"

    click NodePkg "https://github.com/mediar-ai/terminator/blob/main/examples/pdf-to-form/package.json"
    click NodeIndex "https://github.com/mediar-ai/terminator/blob/main/examples/pdf-to-form/src/index.ts"

    click RustSimple "https://github.com/mediar-ai/terminator/blob/main/examples/simple.rs"
    click RustButtonC "https://github.com/mediar-ai/terminator/blob/main/examples/button/Cargo.toml"
    click RustButtonSrc "https://github.com/mediar-ai/terminator/blob/main/examples/button/src/main.rs"
    click RustWinAuto "https://github.com/mediar-ai/terminator/blob/main/examples/win_automation.rs"

    click PyClientEx "https://github.com/mediar-ai/terminator/blob/main/examples/client_example.py"
    click PyNotepad "https://github.com/mediar-ai/terminator/blob/main/examples/notepad.py"

    %% Styles
    classDef rust fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef sdk fill:#a2d5f2,stroke:#333,stroke-width:1px
    classDef client fill:#f2c66a,stroke:#333,stroke-width:1px
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
```
