# go-vgo/robotgo architecture

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

- Interactive diagram: https://gitdiagram.com/go-vgo/robotgo
- Repository: https://github.com/go-vgo/robotgo

## Overview

##### Main Components
- Core Library (base): This directory contains basic definitions, utility functions, and low-level support (e.g., bitmap manipulation, basic types, and OS abstractions) that underlie many other components.
- Input Handling:
- Keyboard (key): Provides functionality for simulating key presses and keystroke combinations.
- Mouse (mouse): Contains implementations for mouse movements, clicks, and other pointer operations. Notice OS-specific files such as mouse_darwin.go, mouse_windows.go, and mouse_x11.go.
- Screen Operations:
- CV (cv): Offers higher-level computer vision (CV) related functions that might leverage captured images.
- Window Management (window): Deals with window-related operations such as finding window handles, setting alerts, and active window controls.
- Clipboard Handling (clipboard): Handles the cross-platform copying and pasting functionality (notice the different file implementations per operating system).
- Event and Hook Management (event): Provides support for registering and handling global events and low-level hook integrations. The structure also mirrors mobile implementations (android and iOS).
- Examples and Command-line Tools:
- Examples: Directory includes sample use cases demonstrating the library’s capabilities.
- Command-line tools in clipboard/cmd (gocopy, gopaste): Illustrate how to expose some functions as standalone utilities.
- External Bindings:
- Binding wrappers for Android ADB and robotn for multi-language support.
- CI/CD & Build/Deployment:
- Various configuration files (.circleci, .github, appveyor.yml, travis.yml) represent the integration and testing pipeline ensuring the project works across multiple environments.

##### Relationships and Interactions
- At the center, the RobotGo core orchestrates the automation functionality. It relies on base for low-level support and offers APIs that are consumed by other parts of the system as well as by client applications.
- The input components (keyboard and mouse) interact directly with OS-level APIs via their differentiation in source files (indicating abstraction for each platform).
- Screen capture and image processing (screen and cv) operate by capturing raw bitmap data (from base) and then either converting it to images or processing it (with optional external library integration like “imgo” or “gcv”).
- The clipboard and window modules encapsulate specialized OS interactions for clipboard operations and window management respectively.
- The event component acts as the hub for catching and dispatching OS and hardware events to user-registered handlers.
- The examples demonstrate usage and serve as integration tests where these components naturally interact.

##### Architectural Patterns and Design Principles
- Abstraction Layers: Notice the clear separation between high-level API calls (RobotGo’s exposed functions) and low-level, OS-specific operations (different *.go files and headers for Darwin, Windows, X11).
- Platform-Dependent Modules: Use of conditional compilation and file naming (e.g., *_darwin.go, *_windows.go) reinforces a layered design that abstracts platform differences.
- Modularity: Each functionality (clipboard, window, input, etc.) is divided into its own package making the system easier to understand and extend.
- External Dependency Integration: The inclusion of bindings (ADB, Robotn) supports a loosely coupled integration, which allows the library to extend functionalities with third-party tools.

##### Final Advice
- Every component is represented—even if it seems small, the OS-specific files and utilities demonstrate important design decisions (modularity and platform abstraction).
- Avoid unnecessary complexity but capture all critical boundaries; sometimes separating the project into as many distinct components as possible (as seen here) gives clarity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["RobotGo API"]:::api
    B["Core Library (base)"]:::core
    C["Input Handling – Keyboard Module"]:::input
    D["Input Handling – Mouse Module"]:::input
    E["Screen Operations – Screen"]:::screen
    F["Screen Operations – CV"]:::screen
    G["Window Management"]:::window
    H["Clipboard Handling"]:::clipboard
    I["Event & Hook Management"]:::event
    J["External Bindings – ADB"]:::external
    K["External Bindings – Mobile Automation"]:::external
    L["Examples"]:::examples
    M["Command-line Tools"]:::examples
    N["CI/CD & Build/Deployment"]:::cicd

    subgraph "Mouse OS-specific Implementations"
        D1["Mouse (macOS)"]:::os
        D2["Mouse (Windows)"]:::os
        D3["Mouse (Linux/X11)"]:::os
    end

    subgraph "Event - Mobile Specific"
        I1["Event (Android)"]:::os
        I2["Event (iOS)"]:::os
    end

    subgraph "CI/CD Pipelines"
        N1["CircleCI"]:::cicd
        N2["GitHub Workflows"]:::cicd
        N3["Appveyor"]:::cicd
        N4["Travis CI"]:::cicd
    end

    %% Connections from RobotGo API
    A -->|"uses"| B
    A -->|"triggers"| C
    A -->|"triggers"| D
    A -->|"calls"| E
    A -->|"manages"| G
    A -->|"handles"| H
    A -->|"registers"| I
    A -->|"integrates"| J
    A -->|"integrates"| K
    A -->|"demonstrates"| L
    A -->|"verified by"| N

    %% Internal module connections
    E -->|"feeds"| F
    H -->|"exposes"| M
    D ---|"OS-specific"| D1
    D ---|"OS-specific"| D2
    D ---|"OS-specific"| D3
    I ---|"platform branch"| I1
    I ---|"platform branch"| I2

    %% Click Events
    click B "https://github.com/go-vgo/robotgo/tree/master/base/"
    click C "https://github.com/go-vgo/robotgo/tree/master/key/"
    click D "https://github.com/go-vgo/robotgo/tree/master/mouse/"
    click E "https://github.com/go-vgo/robotgo/tree/master/screen/"
    click F "https://github.com/go-vgo/robotgo/tree/master/cv/"
    click G "https://github.com/go-vgo/robotgo/tree/master/window/"
    click H "https://github.com/go-vgo/robotgo/tree/master/clipboard/"
    click I "https://github.com/go-vgo/robotgo/tree/master/event/"
    click I1 "https://github.com/go-vgo/robotgo/tree/master/event/android"
    click I2 "https://github.com/go-vgo/robotgo/tree/master/event/ios"
    click L "https://github.com/go-vgo/robotgo/tree/master/examples/"
    click M "https://github.com/go-vgo/robotgo/tree/master/clipboard/cmd/"
    click J "https://github.com/go-vgo/robotgo/blob/master/robotgo_adb.go"
    click K "https://github.com/go-vgo/robotgo/blob/master/robotgo_android.go"
    click N1 "https://github.com/go-vgo/robotgo/tree/master/.circleci/"
    click N2 "https://github.com/go-vgo/robotgo/tree/master/.github/"
    click N3 "https://github.com/go-vgo/robotgo/blob/master/appveyor.yml"
    click N4 "https://github.com/go-vgo/robotgo/blob/master/.travis.yml"

    %% Styles
    classDef api fill:#f9c,stroke:#333,stroke-width:2px
    classDef core fill:#bbf,stroke:#333,stroke-width:2px
    classDef input fill:#cff,stroke:#333,stroke-width:2px
    classDef screen fill:#fcf,stroke:#333,stroke-width:2px
    classDef window fill:#afa,stroke:#333,stroke-width:2px
    classDef clipboard fill:#ffa,stroke:#333,stroke-width:2px
    classDef event fill:#eef,stroke:#333,stroke-width:2px
    classDef external fill:#fdd,stroke:#333,stroke-width:2px
    classDef examples fill:#dfd,stroke:#333,stroke-width:2px
    classDef cicd fill:#ddd,stroke:#333,stroke-width:2px
    classDef os fill:#efe,stroke:#333,stroke-width:2px
```
