# elleoma/facinus architecture

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

- Interactive diagram: https://gitdiagram.com/elleoma/facinus
- Repository: https://github.com/elleoma/facinus

## Overview

##### Project type and purpose
- This is an operations‐oriented deployment tool (“FACINUS”) for Ubuntu/Debian machines. It automates installing and configuring:
- SSH server
- Wake-On-LAN support
- A “fake” power-off script to keep the machine alive
- gsocket tunnel for remote access
- A lightweight Apache+PHP web interface for administration and logs
- Stealth/evasion techniques
- The README and scripts target command-line installers and a simple web UI.

##### File structure
- Top‐level:
- config/ – default configuration scripts
- install – entrypoint script that orchestrates everything
- scripts/ – modular shell scripts (dependencies, deploy modes, detection, script generation, argument parsing)
- web/ – static + PHP files for the web interface and a log-receiver endpoint
- screenshots/ – reference images of the UI
- Deployment variations under scripts/deploy/ allow full, minimal, quiet, etc.
- web_setup.sh – helper to place web files and configure Apache.
- .gitignore and README.md sit at root.

##### README
- Confirms purpose and major features.
- Describes URLs for deployment front page, admin panel, log receiver.
- Mentions gsocket service, stealth, power-off, WOL.

##### Main components and their interactions
a. Components:
1. Administrator’s workstation (browser)
2. Target Ubuntu/Debian server (the machine receiving the install)
3. Installer scripts (shell scripts under root)
4. Apache HTTPD + PHP backend
5. Web frontend (HTML/CSS/JS in web/)
6. gsocket daemon/service
7. SSH daemon
8. WOL module (shell scripts invoking ethtool/magic packets)
9. Logging subsystem (PHP log_receiver.php + file store)
10. “Fake power-off” watchdog
b. Relationships & data flows:
- Admin triggers `sudo ./install` on the target.
- install → scripts/process_args, detect_system → install dependencies → configure SSH, WOL, stealth.
- web_setup.sh copies web files into Apache’s document root.
- install registers gsocket service and starts it, making the server reachable externally.
- The web interface allows admin to view logs, retrieve secrets, and generate client-side setup commands. Those commands use curl to pull gsocket-based bootstrapping.
- log_receiver.php ingests client-side logs and stores them.
c. Architectural patterns:
- Script-driven orchestration layered on Linux services.
- Simple 3-tier model: Shell/CLI installer → Web backend (PHP) → Frontend UI (HTML/CSS/JS).
- Modular shell scripts for separation of concerns (dependency detection, deployment modes).
d. Key technologies:
- Bash shell scripting, pacman/APT package calls
- Apache2 + PHP
- gsocket.io service
- SSHD, ethtool (for WOL), inotify/timers for fake power-off

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Administrator Workstation"
        Browser["Browser"]:::frontend
    end

    subgraph "Networks"
        LAN["LAN"]:::network
        Internet["Internet"]:::network
    end

    subgraph "Target Machine"
        subgraph "Installer Layer"
            Install["install"]:::shell
            Defaults["config/defaults.sh"]:::shell
            Deps["scripts/dependencies.sh"]:::shell
            Detect["scripts/detect_system.sh"]:::shell
            Args["scripts/process_args.sh"]:::shell
            Gen["scripts/generate_scripts.sh"]:::shell
            WebSetup["web/web_setup.sh"]:::shell
            subgraph "Deploy Modes"
                Full["full"]:::shell
                Minimal["minimal"]:::shell
                Quiet["quiet"]:::shell
            end
        end

        subgraph "Services Layer"
            SSHD["SSHD"]:::service
            gsocket["gsocket daemon"]:::service
        end

        subgraph "Web Server"
            Apache["Apache HTTPD + PHP"]:::web
            Frontend["web/index.html"]:::frontend
            AdminPHP["web/admin/admin.php"]:::web
            ScriptsJS["web/admin/scripts.js"]:::frontend
            StylesCSS["web/admin/styles.css"]:::frontend
            LogRecv["web/log_receiver.php"]:::web
        end

        subgraph "OS Modules"
            WOL["WOL Module"]:::os
            Watchdog["Fake Power-Off Watchdog"]:::os
        end

        subgraph "Data Store"
            Logs[(Log Files)]:::store
        end
    end

    %% Installer flow
    Browser -->|SSH| Install
    Install --> Defaults
    Install --> Deps
    Install --> Detect
    Install --> Args
    Install --> Gen
    Install --> Full
    Install --> Minimal
    Install --> Quiet
    Install --> WebSetup
    Gen --> WOL
    Gen --> Watchdog
    WebSetup --> Apache
    WebSetup --> Frontend
    WebSetup --> AdminPHP
    WebSetup --> StylesCSS
    WebSetup --> ScriptsJS

    %% Runtime interactions
    Browser -->|HTTP /, /admin| Apache
    Apache -->|executes| AdminPHP
    AdminPHP -->|writes| Logs
    Browser -->|fetch static| Frontend
    Frontend -->|AJAX| ScriptsJS
    Frontend -->|HTTP POST| LogRecv
    LogRecv -->|stores| Logs

    LAN ---|SSH| SSHD
    LAN -->|Magic Packet| WOL
    Internet ---|gsocket tunnel| gsocket
    gsocket -->|local bind| SSHD

    %% Click Events
    click Install "https://github.com/elleoma/facinus/tree/master/install"
    click Defaults "https://github.com/elleoma/facinus/blob/master/config/defaults.sh"
    click Deps "https://github.com/elleoma/facinus/blob/master/scripts/dependencies.sh"
    click Detect "https://github.com/elleoma/facinus/blob/master/scripts/detect_system.sh"
    click Args "https://github.com/elleoma/facinus/blob/master/scripts/process_args.sh"
    click Gen "https://github.com/elleoma/facinus/blob/master/scripts/generate_scripts.sh"
    click Full "https://github.com/elleoma/facinus/tree/master/scripts/deploy/full"
    click Minimal "https://github.com/elleoma/facinus/tree/master/scripts/deploy/minimal"
    click Quiet "https://github.com/elleoma/facinus/tree/master/scripts/deploy/quiet"
    click WebSetup "https://github.com/elleoma/facinus/blob/master/web/web_setup.sh"
    click Frontend "https://github.com/elleoma/facinus/blob/master/web/index.html"
    click AdminPHP "https://github.com/elleoma/facinus/blob/master/web/admin/admin.php"
    click ScriptsJS "https://github.com/elleoma/facinus/blob/master/web/admin/scripts.js"
    click StylesCSS "https://github.com/elleoma/facinus/blob/master/web/admin/styles.css"
    click LogRecv "https://github.com/elleoma/facinus/blob/master/web/log_receiver.php"

    %% Styles
    classDef shell fill:#cceeff,stroke:#0000cc
    classDef service fill:#ccffcc,stroke:#008800
    classDef web fill:#ffe0cc,stroke:#cc6600
    classDef frontend fill:#ffd8a8,stroke:#cc6600
    classDef os fill:#e0e0e0,stroke:#888888
    classDef network fill:#f0f0f0,stroke:#bbbbbb
    classDef store fill:#ffffcc,stroke:#999900
```
