# alex3025/ilo-fans-controller architecture

> Architecture diagram of the GitHub repository alex3025/ilo-fans-controller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alex3025/ilo-fans-controller
- Repository: https://github.com/alex3025/ilo-fans-controller

## Overview

##### Project type and purpose
- This is a lightweight, single-page full-stack web tool (“iLO Fans Controller”) written in PHP. It exposes a clean UI (Alpine.js + TailwindCSS) to retrieve and set HP iLO server fan speeds via iLO’s REST API (php-curl) and a patched SSH interface (php-ssh2). It can run as a standalone PHP script inside Docker, or be deployed manually on Apache+PHP.

##### File structure
Top-level entries:
- .github/… – CI/CD workflows (build & push Docker image)
- Dockerfile & docker-compose.yaml – container build & runtime orchestration
- config.inc.php(.env) – environment-specific credentials (ILO_HOST, ILO_USER, ILO_PASS)
- ilo-fans-controller.php (renamed to index.php) – the single monolithic script implementing both UI and API endpoints
- presets.json (created at runtime) – persistent fan-preset storage
- README.md, LICENSE.md, .gitignore – docs and metadata

##### README for additional insights
- Explains the dual use of php-curl for GET fan speeds and php-ssh2 for POST commands
- Describes the simple API (GET?api=fans, POST JSON) and filesystem-backed presets.json
- Provides Docker & manual install guides, emphasizing environment variables and web server setup

##### Main components
a. User Browser (Client)
- Alpine.js & TailwindCSS UI served over HTTP(S)
- AJAX calls to API endpoints (same index.php)
b. Web Application Container
- Apache2 + PHP 8.x runtime
- index.php core logic (UI rendering + API routing)
- config.inc.php (loaded from env or file)
- presets.json (persistent JSON store)
c. External iLO Server (Target Hardware)
- iLO REST API endpoint (HTTPS, consumed via php-curl)
- Patched iLO SSH interface (TCP port 22, consumed via php-ssh2)
d. DevOps/CI Pipeline (optional)
- GitHub Actions builds Docker image & pushes to GHCR
- docker-compose / Dockerfile orchestrates container deployment

##### Relationships and interactions
- Browser → HTTP GET to index.php → serves HTML + CSS + JS
- Browser → AJAX GET (?api=fans) → index.php invokes php-curl → iLO REST → returns JSON → index.php returns JSON → browser updates UI
- Browser → AJAX POST (action=fans) → index.php invokes php-ssh2 → iLO SSH → fan speed set → optionally writes presets.json → returns status JSON
- Deployment: GitHub Actions → Docker image → Container registry → docker-compose deploys container ← config.env mounted

##### Architectural patterns & design principles
- Single-file monolith: UI + API in one PHP script for simplicity of deployment
- Layered separation: Presentation (Alpine.js + Tailwind), Business logic (PHP handlers), Persistence (JSON file), Infrastructure (Docker/Apache)
- External integration: clearly delineated HTTP vs. SSH channels to iLO

##### Technologies & libraries
- Frontend: Alpine.js, TailwindCSS
- Server-side: PHP 8.x, php-curl, php-ssh2, Apache 2 (or built-in PHP server in Docker)
- Container: Dockerfile, docker-compose.yaml
- CI/CD: GitHub Actions, GHCR

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        GH_Actions["GitHub Actions"]:::ci
        FUNDING["FUNDING.yml"]:::ci
    end

    GH_Actions -->|"build & push"| Dockerfile["Dockerfile"]:::ci
    GH_Actions -->|"uses metadata"| FUNDING
    click GH_Actions "https://github.com/alex3025/ilo-fans-controller/blob/main/.github/workflows/build-and-push.yml"
    click FUNDING "https://github.com/alex3025/ilo-fans-controller/blob/main/.github/FUNDING.yml"

    %% Deployment
    Dockerfile -->|"builds image"| GHCR["Container Registry"]:::ci
    GHCR -->|"image pulled by"| Compose["docker-compose.yaml"]:::ci
    click Compose "https://github.com/alex3025/ilo-fans-controller/blob/main/docker-compose.yaml"

    %% Application Container
    subgraph "App Container\n(Apache2 + PHP 8.x)" 
        direction TB
        index["index.php\n(UI + API)"]:::app
        config["config.inc.php"]:::app
        envTemplate["config.inc.php.env"]:::app
        presets["presets.json"]:::app
    end

    Compose -->|"runs container with env vars"| index
    click index "https://github.com/alex3025/ilo-fans-controller/blob/main/ilo-fans-controller.php"
    click config "https://github.com/alex3025/ilo-fans-controller/blob/main/config.inc.php"
    click envTemplate "https://github.com/alex3025/ilo-fans-controller/blob/main/config.inc.php.env"

    %% Client
    Browser["User Browser\n(Alpine.js + TailwindCSS)"]:::client
    Browser -->|"1: HTTP GET /index.php"| index
    Browser -->|"2: AJAX GET ?api=fans"| index
    Browser -->|"3: AJAX POST action=fans"| index

    %% Internal logic flows
    index -->|"curl (HTTPS)"| ILO_REST["iLO REST API\n(HTTPS 443)"]:::external
    index -->|"ssh2 (TCP 22)"| ILO_SSH["iLO SSH Interface\n(SSH 22)"]:::external
    index -->|"reads/writes"| presets

    %% External Services
    subgraph "External iLO Server"
        direction TB
        ILO_REST
        ILO_SSH
    end

    %% Documentation
    subgraph "Documentation & Metadata"
        direction TB
        README["README.md"]:::docs
        LICENSE["LICENSE.md"]:::docs
        GITIGNORE[".gitignore"]:::docs
    end
    click README "https://github.com/alex3025/ilo-fans-controller/blob/main/README.md"
    click LICENSE "https://github.com/alex3025/ilo-fans-controller/blob/main/LICENSE.md"
    click GITIGNORE "https://github.com/alex3025/ilo-fans-controller/blob/main/.gitignore"

    %% Styles
    classDef client fill:#cce5ff,stroke:#005cbf,color:#005cbf;
    classDef app fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#ffeeba,stroke:#856404,color:#856404;
    classDef ci fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef docs fill:#f8d7da,stroke:#721c24,color:#721c24;
```
