# gbwgoo/gohook architecture

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

- Interactive diagram: https://gitdiagram.com/gbwgoo/gohook
- Repository: https://github.com/gbwgoo/gohook

## Overview

This project (gohook) is a Go library that provides cross-platform global event hooking based on libuiohook. The library allows users to register keyboard and mouse events and receive callbacks when these events occur. The project is structured to support multiple target operating systems (macOS/Darwin, Windows, X11 on Linux) and provides both a public Go API and underlying platform-specific implementations.

##### Main Components
- Public API Layer: Represented by files like hook.go, event.go, keycode.go, and tables.go. This layer exposes functions such as Register, Start, and End, which allow end users to register event listeners and process events.
- Event Layer: Managed by the “event” directory that provides event dispatch and handling logic (e.g., dispatch_proc.h, goEvent.h, pub.h). This layer converts raw event data into Go events used by the API.
- Platform-Specific Hook Implementations: The “hook” directory contains subdirectories for different OS platforms (darwin, windows, x11). Each one encapsulates its own C header files and logic (e.g., hook_c.h, event_c.h, input.h) to interface with the corresponding OS level hooks.
- Channel/Communication Abstraction: The “chan” directory suggests the existence of channel-based communication or event buffering that underpins the asynchronous event handling.

##### Relationships and Interactions
- The Public API receives user calls, for example, hook.Register to subscribe to specific key events.
- Once a subscription is in place, the API delegates to the Event Layer, which is responsible for capturing, dispatching, and processing lower-level events.
- The Event Layer interacts with the Platform-Specific Implementations under the “hook” directory. Depending on the environment (macOS, Windows, Linux), the appropriate platform module is invoked.
- The processed events are then sent back through a channel (or similar mechanism) so that the user’s callback function in Go is triggered.

##### Architectural Patterns and Design Principles
- Abstraction & Adapter Pattern: The project abstracts OS-specific details behind a common API, ensuring that the application code remains consistent across platforms.
- Separation of Concerns: Clearly differentiates between API handling (Go level), event processing (conversion and dispatch), and OS-specific implementations (native code under hook/).
- Asynchronous Event Processing: Implements channels to manage event data flow between the native hook callbacks and Go’s event loop.

##### Relevant Technologies, Frameworks, or Libraries
- Go modules (go.mod and go.sum) for dependency management.
- libuiohook as an underlying dependency.
- Continuous Integration tools indicated by configs (GitHub workflows, CircleCI, Appveyor) – while not directly architectural, they illustrate how quality assurance is integrated with the build process.
- C interop via cgo, as seen in references to header files (for instance, extern.go).

##### Detail and Clarity
- Clearly relate how a user’s call flows from high-level hook registration through the engine, down to the platform-specific code, and back as processed events.
- Optionally, include a small inset or note about how continuous integration (CI/CD pipelines) supports the build/testing of these modules, though this is less critical than the interaction of the main components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    USER["User Application"]:::user

    %% Public API Layer
    subgraph "Public API Layer"
        API1["hook.go"]:::goapi
        API2["event.go"]:::goapi
        API3["keycode.go"]:::goapi
        API4["tables.go"]:::goapi
    end

    %% Event Handling Layer
    subgraph "Event Handling Layer"
        EVT1["dispatch_proc.h"]:::event
        EVT2["goEvent.h"]:::event
        EVT3["os.h"]:::event
        EVT4["pub.h"]:::event
    end

    %% Channel/Communication Abstraction
    subgraph "Channel/Communication"
        CHAN["eb_chan.h"]:::channel
    end

    %% Platform-Specific Implementations
    subgraph "Platform-Specific Implementations"
        subgraph "Darwin Implementation"
            D1["event_c.h"]:::native
            D2["hook_c.h"]:::native
            D3["input.h"]:::native
            D4["input_c.h"]:::native
            D5["properties_c.h"]:::native
        end
        subgraph "Windows Implementation"
            W1["event_c.h"]:::native
            W2["hook_c.h"]:::native
            W3["input.h"]:::native
            W4["input_c.h"]:::native
            W5["properties_c.h"]:::native
        end
        subgraph "X11 Implementation"
            X1["event_c.h"]:::native
            X2["hook_c.h"]:::native
            X3["input.h"]:::native
            X4["input_c.h"]:::native
            X5["properties_c.h"]:::native
        end
    end

    %% Connections
    USER -->|"invokes"| API1
    API1 -->|"registers"| EVT1
    EVT1 -->|"dispatches"| CHAN
    CHAN -->|"forwards"| D1
    CHAN -->|"forwards"| W1
    CHAN -->|"forwards"| X1
    D2 -->|"callback"| EVT2
    W2 -->|"callback"| EVT2
    X2 -->|"callback"| EVT2
    EVT2 -->|"triggers"| API2
    API2 -->|"returns"| USER

    %% Click Events for Public API Layer
    click API1 "https://github.com/gbwgoo/gohook/blob/master/hook.go"
    click API2 "https://github.com/gbwgoo/gohook/blob/master/event.go"
    click API3 "https://github.com/gbwgoo/gohook/blob/master/keycode.go"
    click API4 "https://github.com/gbwgoo/gohook/blob/master/tables.go"

    %% Click Events for Event Handling Layer
    click EVT1 "https://github.com/gbwgoo/gohook/blob/master//event/dispatch_proc.h"
    click EVT2 "https://github.com/gbwgoo/gohook/blob/master//event/goEvent.h"
    click EVT3 "https://github.com/gbwgoo/gohook/blob/master//event/os.h"
    click EVT4 "https://github.com/gbwgoo/gohook/blob/master//event/pub.h"

    %% Click Event for Channel/Communication
    click CHAN "https://github.com/gbwgoo/gohook/tree/master//chan"

    %% Click Events for Darwin Implementation
    click D1 "https://github.com/gbwgoo/gohook/blob/master/hook/darwin/event_c.h"
    click D2 "https://github.com/gbwgoo/gohook/blob/master/hook/darwin/hook_c.h"
    click D3 "https://github.com/gbwgoo/gohook/blob/master/hook/darwin/input.h"
    click D4 "https://github.com/gbwgoo/gohook/blob/master/hook/darwin/input_c.h"
    click D5 "https://github.com/gbwgoo/gohook/blob/master/hook/darwin/properties_c.h"

    %% Click Events for Windows Implementation
    click W1 "https://github.com/gbwgoo/gohook/blob/master/hook/windows/event_c.h"
    click W2 "https://github.com/gbwgoo/gohook/blob/master/hook/windows/hook_c.h"
    click W3 "https://github.com/gbwgoo/gohook/blob/master/hook/windows/input.h"
    click W4 "https://github.com/gbwgoo/gohook/blob/master/hook/windows/input_c.h"
    click W5 "https://github.com/gbwgoo/gohook/blob/master/hook/windows/properties_c.h"

    %% Click Events for X11 Implementation
    click X1 "https://github.com/gbwgoo/gohook/blob/master/hook/x11/event_c.h"
    click X2 "https://github.com/gbwgoo/gohook/blob/master/hook/x11/hook_c.h"
    click X3 "https://github.com/gbwgoo/gohook/blob/master/hook/x11/input.h"
    click X4 "https://github.com/gbwgoo/gohook/blob/master/hook/x11/input_c.h"
    click X5 "https://github.com/gbwgoo/gohook/blob/master/hook/x11/properties_c.h"

    %% Styles
    classDef goapi fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef event fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef channel fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef native fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef user fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
