# iberianpig/fusuma architecture

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

- Interactive diagram: https://gitdiagram.com/iberianpig/fusuma
- Repository: https://github.com/iberianpig/fusuma

## Overview

##### Project Overview and Main Components
- Project Type & Purpose: Fusuma is a Ruby-based application that processes touchpad inputs (such as swipes, pinches, rotates, and holds) to trigger configurable commands. It acts both as a daemon listening for multitouch events and as a configurable tool with an extensible plugin system.
- Core Areas: The system comprises a core engine (located in lib/fusuma/) that deals with inputs, configuration, device management, logging, and then a very modular plugin system. Key directories include:
- lib/fusuma (core logic, configuration, device handling, multi_logger, etc.)
- lib/fusuma/plugin (the plugin architecture that is subdivided into various aspects: inputs, filters, detectors, parsers, executors, and events)

##### Detailed Component Breakdown
a. Core Engine:
- Entry Point: The executable (exe/fusuma) calls into the primary module (lib/fusuma.rb) which initializes the environment, loads configuration (found in lib/fusuma/config.rb and config files), and sets up device listeners.
- Configuration: The system reads gesture mapping and sensitivity settings from YAML configuration files (lib/fusuma/config.yml and user’s ~/.config/fusuma/config.yml).
- Device Handling & Environment: Components such as device.rb and environment.rb are responsible for interfacing with /dev/input and setting up an accurate context for gesture recognition.
- Logging: multi_logger.rb is used to track events and errors through the application's lifecycle.

b. Plugin System:
- Modular Plugins: Fusuma offers a robust plugin system to extend its core functions. The system is organized into several key plugin directories:
– Input Plugins (located in lib/fusuma/plugin/inputs): where the raw touchpad events are captured. Notable files include:
- libinput_command_input.rb – handles command-based inputs
- timer_input.rb – manages time-based input events.
– Filter Plugins (located in lib/fusuma/plugin/filters): to pre-process and filter raw events. Primary file is:
- libinput_device_filter.rb – used to validate and filter device-specific events.
– Parser Plugins (located in lib/fusuma/plugin/parsers): to convert filtered input events into gesture events that the system understands. Key file:
- libinput_gesture_parser.rb – responsible for interpreting the raw event sequences.
– Additional Plugins: Beyond these, there are detectors (for identifying swipes, pinches, etc.), executors (which execute configured commands), and event recorders. Though your custom instructions focus on the chain from inputs → filters → parsers, these other plugins complete the flow.

##### Relationships and Data Flow
- Next Stage: From the Filter Plugins, the flow continues to “Parser Plugins” (featuring libinput_gesture_parser.rb) which transform filtered data into actionable gestures.
- Final Routing: Although not specifically in your custom instructions, from the parser stage, consider showing flow toward “Detector Plugins”, “Event Management”, and finally “Executor Plugins” which carry out the actual command (like invoking xdotool) as configured in the YAML files.
- Feedback & Logging: A bi-directional link from all stages back to the “Multi Logger” and “Environment” components can also be drawn to indicate logging, error handling, and environment adjustments.

##### Architectural Patterns & Technologies
- Modular Plugin Architecture: The design relies heavily on a modular plugin pattern which allows easy extension and swapping out of functionality.
- Configuration-Driven Behavior: Emphasize that YAML configuration files drive most behavioral aspects (e.g., gesture mapping, thresholds, and intervals).
- Ruby Ecosystem: Note the use of RubyGems (with fusuma.gemspec and Gemfile) and the separation between production files (in lib/) and tests (in spec/). This is characteristic of well-structured Ruby projects.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Engine Components
    subgraph "Core Engine"
        CE["Core Engine Entry"]:::core
        CFG["Configuration"]:::config
        DEV["Device & Environment"]:::core
        LOG["Multi Logger"]:::core
    end

    %% Plugin System Components
    subgraph "Plugin System"
        subgraph "Input Plugins"
            IP1["libinput_command_input"]:::plugin
            IP2["timer_input"]:::plugin
        end
        subgraph "Filter Plugins"
            FP["libinput_device_filter"]:::plugin
        end
        subgraph "Parser Plugins"
            PP["libinput_gesture_parser"]:::plugin
        end
        DET["Detector Plugins"]:::plugin
        EXE["Executor Plugins"]:::plugin
    end

    %% Data Flow Connections
    CE -->|"initiates"| IP1
    CE -->|"initiates"| IP2

    IP1 -->|"collects"| FP
    IP2 -->|"collects"| FP

    FP -->|"filters"| PP
    PP -->|"parses"| DET
    DET -->|"triggers"| EXE

    %% Feedback & Logging Connections
    PP <-->|"logs"| LOG
    FP <-->|"logs"| LOG
    DEV <-->|"adjusts"| PP

    %% Class Definitions for Colors and Styles
    classDef core fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef config fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef plugin fill:#87CEEB,stroke:#333,stroke-width:2px;

    %% Click Events for Core Engine
    click CE "https://github.com/iberianpig/fusuma/tree/main/exe/fusuma"
    click CE "https://github.com/iberianpig/fusuma/blob/main/lib/fusuma.rb"
    click CFG "https://github.com/iberianpig/fusuma/blob/main/lib/fusuma/config.rb"
    click CFG "https://github.com/iberianpig/fusuma/blob/main/lib/fusuma/config.yml"
    click DEV "https://github.com/iberianpig/fusuma/blob/main/lib/fusuma/device.rb"
    click DEV "https://github.com/iberianpig/fusuma/blob/main/lib/fusuma/environment.rb"
    click LOG "https://github.com/iberianpig/fusuma/blob/main/lib/fusuma/multi_logger.rb"

    %% Click Events for Plugin System
    click IP1 "https://github.com/iberianpig/fusuma/blob/main/lib/fusuma/plugin/inputs/libinput_command_input.rb"
    click IP2 "https://github.com/iberianpig/fusuma/blob/main/lib/fusuma/plugin/inputs/timer_input.rb"
    click FP "https://github.com/iberianpig/fusuma/blob/main/lib/fusuma/plugin/filters/libinput_device_filter.rb"
    click PP "https://github.com/iberianpig/fusuma/blob/main/lib/fusuma/plugin/parsers/libinput_gesture_parser.rb"
```
