# xhmiss/wolgoweb architecture

> Architecture diagram of the GitHub repository xhmiss/wolgoweb, 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/xhmiss/wolgoweb
- Repository: https://github.com/xhmiss/wolgoweb

## Overview

##### Project Overview & Main Purpose
- WolGoWeb is a web API tool that enables triggering Wake-on-LAN (WOL) commands remotely. It’s designed to be deployed on a LAN server or NAS.
- Its primary role is to expose an HTTP API (with an optional Web UI) that—when called—sends a WOL magic packet to power on target machines. It also includes support for optional API authorization using token-based verification.
- The project is written in Go (see go.mod, go.sum, and source files under the src folder) and supports multiple deployment strategies (native binary, Docker, Docker Compose, and even deployment on Synology NAS).

##### Analyzing the File Structure
- Top-level files include versioning (.version, version.bat, version.vbs) and standard git and license files.
- The src folder contains the main Go application files (e.g., main.go and wol.go), where the core logic (HTTP server and WOL functions) is implemented.
- The docker folder includes Dockerfiles, Docker-compose files, and related shell scripts for building container images as well as usage instructions in its own README.
- The presence of a .github/workflows directory indicates CI/CD integration (for example, automated Docker image builds).

##### Core Components to Capture
a. Web/API Server:
- This is the heart of the application. It listens on a configurable port (default 9090) for incoming HTTP requests.
- It provides the Web UI (when enabled) for administrative interaction as well as the REST API endpoints (e.g., /wol endpoint) to trigger the magic packet.

b. WOL Processing Module:
- Separate logical component (represented by the wol.go file) which handles the creation and sending of the Wake-on-LAN magic packet.
- This module is invoked by the HTTP server upon receiving valid WOL requests.

c. Configuration Management:
- The system pulls configuration from command-line flags (e.g., -port, -username, -password, -c, -web, -key) and environment variables.
- This component ensures the application behavior is customizable and supports various deployment scenarios (Docker environment variables versus command-line arguments).

d. Security/Token Verification (Optional):
- When enabled (via key parameter), the API validates incoming requests by computing a token (MD5(key+mac+time)) and comparing it to the token sent by the client.
- This module should be represented to show the security measure built into the request handling.

e. External Clients:

f. Deployment Orchestration:
- Deployment modes: native binary deployment on Windows/Linux, containerization via Docker, Docker Compose, and even specific instructions for platforms such as Synology.
- A “Docker Environment” block to denote container-specific configurations and integration with CI/CD (GitHub Actions).

##### Relationships and Data Flow
- A feedback path from the WOL Module back to the HTTP server for response delivery (e.g., confirmation message).
- For API requests that require validation, show the flow that includes the security module (token generation and verification).

##### Architectural Patterns and Technologies
- Technologies to indicate:
- Golang (as the programming language and runtime)
- Docker & Docker Compose (for container and deployment management)
- GitHub Actions (for CI/CD pipelines)
- HTTP/REST for API communication

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Clients["External Clients<br/>(Browsers, CLI, iOS, NAS Tasks)"]:::client
    end

    subgraph "Application Core"
        API["Web/API Server<br/>(HTTP, Port 9090)"]:::core
        Config["Configuration & Environment Management"]:::config
        Security["Security / Token Verification Module"]:::security
        WOL["WOL Processor<br/>(Sends Magic Packet)"]:::core
    end

    subgraph "Deployment"
        Deploy["Deployment: Native & Containerized"]:::deploy
        Docker["Docker Environment"]:::deploy
        CICD["CI/CD (GitHub Actions)"]:::deploy
    end

    %% Data Flow Connections
    Clients -->|"HTTP request"| API
    API -->|"Uses"| Config
    API -->|"Validates"| Security
    Security -->|"Returns validation"| API
    API -->|"Triggers"| WOL
    WOL -->|"Returns confirmation"| API
    API -->|"Deployed as"| Deploy
    Deploy -->|"Configured via"| Docker
    Docker -->|"Built/Deployed by"| CICD

    %% Click Events
    click API "https://github.com/xhmiss/wolgoweb/blob/master/src/main.go"
    click Config "https://github.com/xhmiss/wolgoweb/blob/master/src/main.go"
    click Security "https://github.com/xhmiss/wolgoweb/blob/master/src/main.go"
    click WOL "https://github.com/xhmiss/wolgoweb/blob/master/src/wol.go"
    click Docker "https://github.com/xhmiss/wolgoweb/tree/master/docker/"
    click CICD "https://github.com/xhmiss/wolgoweb/tree/master/.github/workflows"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef config fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef security fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef deploy fill:#FFA500,stroke:#FF8C00,stroke-width:2px;
    classDef client fill:#FFDAB9,stroke:#CD853F,stroke-width:2px;
```
