# robotn/gohook architecture

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

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

## Overview

##### Project Type Analysis
This is a system-level library that provides cross-platform (Windows, Darwin/macOS, X11/Linux) keyboard and mouse event hooking capabilities, built on top of libuiohook.

##### Main Components

A. Core Components:
- Event System (event/)
- Hook System (hook/)
- Channel Management (chan/)
- Platform-Specific Implementations
- Windows Implementation
- Darwin Implementation
- X11 Implementation

B. Interface Layer:
- Public API (*.go files in root)
- Event Processing Pipeline

**[Use distinct layers from bottom to top]**

**Layer 1 (Platform Layer):**

- Windows      |     Darwin       |       X11       |
- Implementation   | Implementation   | Implementation  |

**Layer 2 (Core Layer):**

- Hook System    |  Event System    | Channel Manager |

**Layer 3 (API Layer):**

- Public Go API                    |

**Layer 4 (Consumer Layer):**

- Client Application                  |

##### Key Elements to Highlight

- Platform-specific code (Blue)
- Core systems (Green)
- Public API (Orange)
- External interfaces (Gray)

b. Connection Types:

##### Important Details

a. Event Flow:
- How events propagate from OS level to user code
- Event dispatch mechanism
- Channel-based communication system

b. Platform Abstraction:
- Demonstrate how the platform-specific code is abstracted
- Common interface that unifies the different platforms

##### Technical Specifications

Key components:
- Event registration system
- Hook management
- Channel-based event processing
- Platform-specific input handling
- Key code translation layer

##### Implementation Notes

- The event-driven nature of the system
- Cross-platform compatibility
- The separation between low-level hooks and high-level API
- The asynchronous processing model using channels

##### Integration Points

Clear integration points for:
- Operating system hooks
- User-defined callbacks
- Event filtering and processing
- Resource cleanup and management

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client["Client Application Layer"]
        App[("Client Application")]:::client
        Example[("Example Implementation")]:::client
    end

    subgraph API["Public API Layer"]
        PublicAPI[("Public Go API")]:::api
        EventInterface[("Event Interface")]:::api
        HookInterface[("Hook Interface")]:::api
        ExternFuncs[("External Functions")]:::api
        KeyCodeMap[("Key Code Mapping")]:::api
        LookupTables[("Lookup Tables")]:::api
    end

    subgraph Core["Core System Layer"]
        EventSystem[("Event System")]:::core
        HookSystem[("Hook System")]:::core
        ChannelMgr[("Channel Manager")]:::core
        EventDispatch[("Event Dispatcher")]:::core
        Logger[("Hook Logger")]:::core
    end

    subgraph Platform["Platform-Specific Layer"]
        Windows[("Windows Implementation")]:::platform
        Darwin[("Darwin Implementation")]:::platform
        X11[("X11 Implementation")]:::platform
    end

    %% Connections
    App --> PublicAPI
    Example --> PublicAPI
    PublicAPI --> EventInterface
    PublicAPI --> HookInterface
    PublicAPI --> ExternFuncs
    PublicAPI --> KeyCodeMap
    PublicAPI --> LookupTables
    
    EventInterface --> EventSystem
    HookInterface --> HookSystem
    EventSystem --> EventDispatch
    HookSystem --> Logger
    EventSystem --> ChannelMgr
    HookSystem --> ChannelMgr
    
    HookSystem --> Windows
    HookSystem --> Darwin
    HookSystem --> X11

    %% Click Events
    click Example "https://github.com/robotn/gohook/blob/master/examples/main.go"
    click EventInterface "https://github.com/robotn/gohook/blob/master/event.go"
    click HookInterface "https://github.com/robotn/gohook/blob/master/hook.go"
    click ExternFuncs "https://github.com/robotn/gohook/blob/master/extern.go"
    click KeyCodeMap "https://github.com/robotn/gohook/blob/master/keycode.go"
    click LookupTables "https://github.com/robotn/gohook/blob/master/tables.go"
    click EventSystem "https://github.com/robotn/gohook/tree/master/event/"
    click EventDispatch "https://github.com/robotn/gohook/blob/master/event/dispatch_proc.h"
    click HookSystem "https://github.com/robotn/gohook/tree/master/hook/"
    click Logger "https://github.com/robotn/gohook/blob/master/hook/logger.h"
    click Windows "https://github.com/robotn/gohook/tree/master/hook/windows/"
    click Darwin "https://github.com/robotn/gohook/tree/master/hook/darwin/"
    click X11 "https://github.com/robotn/gohook/tree/master/hook/x11/"
    click ChannelMgr "https://github.com/robotn/gohook/blob/master/chan/eb_chan.h"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px
    classDef api fill:#fd8,stroke:#333,stroke-width:2px
    classDef core fill:#9f9,stroke:#333,stroke-width:2px
    classDef platform fill:#9cf,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        Client_L[("Client Layer")]:::client
        API_L[("API Layer")]:::api
        Core_L[("Core Layer")]:::core
        Platform_L[("Platform Layer")]:::platform
    end
```
