# healer37/edgewindow architecture

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

- Interactive diagram: https://gitdiagram.com/healer37/edgewindow
- Repository: https://github.com/healer37/edgewindow

## Overview

##### Main Components
- Bootstrapping & Initialization:
- init.lua – This is the entry point where the module is required by Hammerspoon.
- config.lua – Holds user-defined settings and configuration parameters.
- Core Functional Modules:
- EdgeManager.lua – Handles the logic for moving windows to screen edges.
- MenuBar.lua – Provides the menu bar interface for controlling and displaying window management status.
- StateManager.lua – Manages the storage and recall of window states (position, size), maintaining state memory.
- WindowManager.lua – Deals with the resizing, positioning, and actual manipulation of windows.
- log.lua – Offers logging functionality to help with debugging and tracing state changes.
- Auxiliary & Asset Directories:
- Documentation & Workflow:
- CONFIG.md, DEVELOPMENT.md, WORKFLOW.md – Provide instructions, development guidelines, and system workflow details.

##### Relationships & Interactions
- The bootstrap in init.lua loads the configuration (config.lua) and then initializes all primary modules (EdgeManager, MenuBar, StateManager, WindowManager).
- The EdgeManager is the primary driver that listens for window events (e.g., dragging windows near the screen edges) and then triggers actions.
- The WindowManager directly handles the window manipulation based on actions initiated by the EdgeManager.
- The StateManager keeps track of window state and remembers settings across sessions.
- The MenuBar module provides a user interface for quick actions and status updates; it receives updates from StateManager and possibly from the WindowManager.
- The log module is used throughout for recording detailed operations, errors, and debugging info.

##### Notable Architectural Patterns & Principles
- Modular Design: Each functionality (edge handling, state management, UI, and window manipulation) is encapsulated in its own Lua module.
- Event-Driven Architecture: The system appears to be event-based, where window position changes, user inputs (keyboard shortcuts, mouse movements) trigger events processed by the respective managers.
- Performance Considerations: As pointed out in the README’s performance discussion, there is attention given to handling rapid sequences of events (through batching / event queue strategies) to reduce synchronous processing delays.

##### Technologies & Dependencies
- Hammerspoon: This is the underlying engine enabling access to macOS events and window management APIs. All modules are built on top of Hammerspoon's Lua environment.
- Lua: The primary programming language.
- macOS APIs: Interaction with windowing aspects is done via macOS internals provided by Hammerspoon.

##### Final Checklist for the Principal Software Engineer
- Components like Bootstrap (init.lua, config.lua), Core Modules (EdgeManager, WindowManager, StateManager), and the MenuBar UI module are clearly labeled.
- Adding annotations for performance optimizations, such as the event batching mechanism discussed in the README, identifying where these optimizations take place within the overall flow.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Runtime Environment
    HS["Hammerspoon"]:::external

    %% Bootstrap and Initialization
    subgraph "Bootstrap & Initialization"
        init["init.lua"]:::bootstrap
        cfg["config.lua"]:::bootstrap
    end

    %% Core Functional Modules
    subgraph "Core Modules"
        edge["EdgeManager"]:::core
        win["WindowManager"]:::core
        state["StateManager"]:::core
    end

    %% User Interface Module
    subgraph "User Interface"
        menu["MenuBar"]:::ui
    end

    %% Logging Module
    subgraph "Utilities"
        logNode["log"]:::logging
    end

    %% Documentation
    subgraph "Documentation & Guidelines"
        confMd["CONFIG.md"]:::doc
        devMd["DEVELOPMENT.md"]:::doc
        workflowMd["WORKFLOW.md"]:::doc
    end

    %% Graphical Assets
    subgraph "Graphical Assets"
        iconsNode["icons"]:::asset
    end

    %% Connections: Initialization Flow
    HS -->|"calls"| init
    init -->|"loads"| cfg
    init -->|"initializes"| edge
    init -->|"initializes"| win
    init -->|"initializes"| state
    init -->|"initializes"| menu
    init -->|"sets up"| logNode

    %% Connections: Module Interactions
    edge -->|"triggers"| win
    edge -->|"updates"| state
    win -->|"sendsUpdate"| menu
    state -->|"sendsUpdate"| menu

    %% Logging interactions (bidirectional logging for diagnostics)
    edge <-->|"logs"| logNode
    win <-->|"logs"| logNode
    state <-->|"logs"| logNode
    menu <-->|"logs"| logNode
    cfg <-->|"logs"| logNode

    %% Class Definitions for styling
    classDef bootstrap fill:#cce5ff,stroke:#339,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef ui fill:#ffeeba,stroke:#ffc107,stroke-width:2px;
    classDef logging fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef doc fill:#cff4fc,stroke:#17a2b8,stroke-width:2px;
    classDef asset fill:#fdfd96,stroke:#f39c12,stroke-width:2px;

    %% Click Events
    click init "https://github.com/healer37/edgewindow/blob/main/init.lua"
    click cfg "https://github.com/healer37/edgewindow/blob/main/config.lua"
    click edge "https://github.com/healer37/edgewindow/blob/main/EdgeManager.lua"
    click win "https://github.com/healer37/edgewindow/blob/main/WindowManager.lua"
    click state "https://github.com/healer37/edgewindow/blob/main/StateManager.lua"
    click menu "https://github.com/healer37/edgewindow/blob/main/MenuBar.lua"
    click logNode "https://github.com/healer37/edgewindow/blob/main/log.lua"
    click iconsNode "https://github.com/healer37/edgewindow/tree/main/icons"
    click confMd "https://github.com/healer37/edgewindow/blob/main/CONFIG.md"
    click devMd "https://github.com/healer37/edgewindow/blob/main/DEVELOPMENT.md"
    click workflowMd "https://github.com/healer37/edgewindow/blob/main/WORKFLOW.md"
```
