# liquidgalaxylab/liquid-galaxy architecture

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

- Interactive diagram: https://gitdiagram.com/liquidgalaxylab/liquid-galaxy
- Repository: https://github.com/liquidgalaxylab/liquid-galaxy

## Overview

##### Main Components
- Master & Slave Systems – these hardware nodes work together in a coordinated multi-screen setup. The “earth/config/master” and “earth/config/slave” directories and the installation instructions in the README show that different configuration files are prepared for each role.
- Google Earth/Display Engine – the “earth/builds”, “earth/scripts”, and related configuration files represent the Google Earth Pro environment being deployed.
- System Configuration – the “gnu_linux” directory contains Linux configuration files (Xsession, Apache, network settings, etc.) to ensure that the operating system is set up correctly for the Liquid Galaxy display.
- Touchscreen & API Interface – the “php-interface” directory provides PHP code for a web-based touchscreen interface, which enables users to control queries and coordinates sent to the display. This may be accessed over a web server setup.
- Additional Tools & Utilities – includes utilities like “spacenav-rezero” (for recalibrating input devices), “input_event” for low-level event handling, and even “kamelopard” and “lg-pano” for additional functionality (such as geocoding or panoramic image processing).

##### Relationships and Interactions
- The Master node serves as the central configuration and control point. It deploys configuration files (from “earth/config/master”) and drives the overall setup.
- Slave nodes retrieve their settings from the master (configured via SSH and file synchronization during installation) and use “earth/config/slave” files.
- The installation scripts (e.g., “install.sh” and various scripts in “earth/scripts”) are used to synchronize, launch, and update services on both master and slave machines.
- The Linux configuration files (“gnu_linux”) are applied at the OS level to configure X sessions, network, Apache, and other essential services.
- The PHP-based interface on the “php-interface” side acts as an external control API to send KML files or commands to the system.
- Supplementary components (like “spacenav-rezero” and “input_event”) offer low-level controls for input devices that may affect navigation within Google Earth – indicating clear integration with hardware input.

##### Architectural Patterns and Design Principles
- Distributed Deployment: The architecture must represent distinct nodes (master and slaves) with clear inter-node communication (for configuration syncing and command initiation).
- Separation of Concerns: Different directories indicate modular separation between display configurations (“earth”), system and OS integration (“gnu_linux”), interactive interfaces (“php-interface”), and additional utilities.
- Integration Layers: There is a tight coupling between low-level system configuration (via Linux settings), application-level configuration (Google Earth through “earth/builds” and “earth/scripts”), and interactive API layers (PHP and even Ruby utilities in “kamelopard”).
- Script-driven Automation: Installation and lifecycle management are driven by shell scripts and utility commands that automate the setup and runtime control.

##### Relevant Technologies and Frameworks
- Google Earth Pro – the visualization and display core.
- Ubuntu/Linux – with specific configurations provided in “gnu_linux”.
- Web Server and PHP – hosting the touchscreen API interface.
- Scripting (Bash, Python) – for installation and orchestration (“install.sh”, various scripts in “earth/scripts”, etc.).
- Ruby (in the “kamelopard” directory) – possibly for geocoding or helper functions.
- Low-level C/C++ code – seen in “spacenav-rezero” and “input_event” for hardware event handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Master Node
    subgraph "Master Node"
        M_Config["Master Config Files (earth/config/master)"]:::masterStyle
        M_GE["Google Earth Engine (earth/builds, earth/scripts)"]:::masterStyle
        M_Config -->|"deploys"| M_GE
    end

    %% Slave Node
    subgraph "Slave Node"
        S_Config["Slave Config Files (earth/config/slave)"]:::slaveStyle
        S_GE["Google Earth Engine (earth/builds, earth/scripts)"]:::slaveStyle
        S_Config -->|"deploys"| S_GE
    end

    %% Global OS Configuration and API Interface
    OS_Config["OS Configuration (gnu_linux)"]:::osStyle
    PHP_Interface["Touchscreen/API Interface (php-interface)"]:::apiStyle

    %% Additional Tools & Utilities
    subgraph "Additional Tools & Utilities"
        spacenav["spacenav-rezero"]:::utilStyle
        input_event["input_event"]:::utilStyle
        kamelopard["kamelopard"]:::utilStyle
        lgpano["lg-pano"]:::utilStyle
    end

    %% Interactions and Relationships
    OS_Config -->|"enables"| M_GE
    OS_Config -->|"enables"| S_GE

    PHP_Interface -->|"sendsCommands"| M_GE

    M_Config <==>|"sync"| S_Config

    spacenav -->|"controls"| M_GE
    spacenav -->|"controls"| S_GE

    input_event -->|"controls"| M_GE
    input_event -->|"controls"| S_GE

    kamelopard -->|"integrates"| M_GE
    kamelopard -->|"integrates"| S_GE

    lgpano -->|"integrates"| M_GE
    lgpano -->|"integrates"| S_GE

    %% Click Events
    click M_Config "https://github.com/liquidgalaxylab/liquid-galaxy/tree/master/earth/config/master"
    click S_Config "https://github.com/liquidgalaxylab/liquid-galaxy/tree/master/earth/config/slave"
    click M_GE "https://github.com/liquidgalaxylab/liquid-galaxy/tree/master/earth/builds"
    click M_GE "https://github.com/liquidgalaxylab/liquid-galaxy/tree/master/earth/scripts"
    click S_GE "https://github.com/liquidgalaxylab/liquid-galaxy/tree/master/earth/builds"
    click S_GE "https://github.com/liquidgalaxylab/liquid-galaxy/tree/master/earth/scripts"
    click OS_Config "https://github.com/liquidgalaxylab/liquid-galaxy/tree/master/gnu_linux"
    click PHP_Interface "https://github.com/liquidgalaxylab/liquid-galaxy/tree/master/php-interface"
    click spacenav "https://github.com/liquidgalaxylab/liquid-galaxy/tree/master/spacenav-rezero"
    click input_event "https://github.com/liquidgalaxylab/liquid-galaxy/tree/master/input_event"
    click kamelopard "https://github.com/liquidgalaxylab/liquid-galaxy/tree/master/kamelopard"
    click lgpano "https://github.com/liquidgalaxylab/liquid-galaxy/tree/master/lg-pano"

    %% Styles
    classDef masterStyle fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef slaveStyle fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef osStyle fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef apiStyle fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef utilStyle fill:#FFD700,stroke:#000,stroke-width:2px;
```
