# hammerspoon/hammerspoon architecture

> Architecture diagram of the GitHub repository hammerspoon/hammerspoon, 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/hammerspoon/hammerspoon
- Repository: https://github.com/hammerspoon/hammerspoon

## Overview

##### Overall Project Layers
- Core Native Layer: This includes the native C/Objective-C code (found throughout the “Hammerspoon” directory and associated Xcode projects) that interacts directly with macOS system APIs.
- Lua Bridge & Scripting Engine: Built using LuaSkin and embedded Lua (with the Lua interpreter source under “LuaSkin/lua-5.4.7”, etc.), this layer exposes native functionality to user-written Lua scripts.
- Extensions Framework: Hammerspoon’s power comes from its many extensions (organized under the “extensions” directory). Each extension—for example “alert”, “appfinder”, “audiodevice”, “screen”, etc.—wraps native functionality into Lua-accessible modules.
- User Configuration: The user’s initialization file (~/.hammerspoon/init.lua) is where custom scripting and configuration take place, using the provided APIs.

##### Major Components to Illustrate
- OS X / macOS System APIs: At the bottom, the operating system’s native interfaces and frameworks.
- Core Application:
– The “Hammerspoon” main application component (as built from sources and Xcode projects) which contains the native bridge code.
– Build configurations and entitlements (referenced in the “Build Configs” directory).
– External dependencies (Pods, third-party libraries like CocoaLumberjack, CocoaHTTPServer, and SocketRocket) that support various functionalities.
- Lua Engine & Bridge:
– The integrated Lua interpreter and LuaSkin (which forms the interface between native code and Lua).
– The bridging logic (for example, files like “MJLua.m”, “HSLogger.m”, etc., in the Hammerspoon directory) that expose system functionality to the scripting side.
- Extensions:
– Some extensions include extra native libraries (for example, “libalert.m”, “libwindow.m”, “libhttp.m”, etc.).
- External Integrations & Community Infrastructure:
– Mention tools like the Podfile, GitHub workflows, and additional directories (e.g., “scripts”, “SPOONS.md”) which illustrate the build and extension lifecycle, though these are more tooling than runtime infrastructure.

##### Relationships and Data Flow
- That the Lua layer in turn calls into the native bridge layer via LuaSkin.
- The native bridge layer communicates with macOS system APIs.
- Extensions form modules that encapsulate specific system functionalities and expose well-defined Lua APIs.

##### Architectural Patterns & Design Principles
- Modularization: The project is split into a core native layer, a scripting layer, and multiple discrete extension modules.
- Separation of Concerns: There is a clear separation between low-level system interactions (native code) and high-level automation and configuration (Lua scripts).
- Bridging Pattern: A key design principle is the bridging mechanism that connects system APIs to Lua through LuaSkin.
- Extensibility: The “extensions” directory shows a plugin-style architecture making it simple to add or update functionality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level Components
    macAPI["macOS System APIs"]:::system
    extModules["Extensions (Modules)"]:::extensions
    extDeps["External Dependencies (Pods)"]:::external
    userScripts["User Scripts (init.lua)"]:::scripts

    %% Subgraph: Lua Engine & Bridge
    subgraph "Lua Engine & Bridge"
        luaCore["LuaSkin"]:::scripting
        luaInterp["Embedded Lua Interpreter"]:::scripting
    end

    %% Subgraph: Hammerspoon Core (Native Layer)
    subgraph "Hammerspoon Core (Native Layer)"
        hsMain["Core Application"]:::native
        hsBuild["Build Configs"]:::native
    end

    %% Data Flow Arrows
    userScripts -->|"calls"| luaCore
    luaCore -->|"bridges"| hsMain
    hsMain -->|"invokes"| macAPI
    hsMain -->|"integrates"| extModules
    hsMain -->|"depends-on"| extDeps
    luaCore -->|"exposes"| extModules

    %% Click Events
    click hsMain "https://github.com/hammerspoon/hammerspoon/tree/master/Hammerspoon"
    click hsBuild "https://github.com/hammerspoon/hammerspoon/tree/master/Hammerspoon/Build Configs"
    click luaCore "https://github.com/hammerspoon/hammerspoon/tree/master/LuaSkin"
    click luaInterp "https://github.com/hammerspoon/hammerspoon/blob/master/LuaSkin/lua-5.4.7"
    click extModules "https://github.com/hammerspoon/hammerspoon/tree/master/extensions"
    click extDeps "https://github.com/hammerspoon/hammerspoon/tree/master/Pods"
    click userScripts "https://github.com/hammerspoon/hammerspoon/blob/master/~/.hammerspoon/init.lua"

    %% Styles
    classDef native fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef scripting fill:#d5f5e3,stroke:#27ae60,stroke-width:2px,rx:5,ry:5;
    classDef system fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef extensions fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef external fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    classDef scripts fill:#d6eaf8,stroke:#3498db,stroke-width:2px,rx:5,ry:5;
```
