# wikihost-opensource/als architecture

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

- Interactive diagram: https://gitdiagram.com/wikihost-opensource/als
- Repository: https://github.com/wikihost-opensource/als

## Overview

##### Main Components
- Frontend (UI):
- Located in the “ui” directory.
- Built with Vue.js (evidenced by the App.vue, Vite configuration, and modern JS tooling like ESLint/Prettier).
- Acts as the client interface where users interact with speed tests, ping utilities, shell, and other network diagnostics.
- Backend:
- Located in the “backend” directory.
- Written in Go.
- Contains the “als” package that hosts the main server logic. Within “als”, there are multiple subdirectories under “controller” (for ping, iperf3, session, shell, speedtest, cache, etc.) that represent distinct functionalities.
- Additional backend components include “config” (to manage initialization, IP configurations, and environment variables), “http” (to handle HTTP server initialization and route handling), and “timer” (for scheduling tasks like traffic monitoring).
- There’s also a separate “fakeshell” module which provides a shell simulation interface.
- Embedded UI assets in “backend/embed/ui” indicate that parts of the frontend might be integrated directly within the backend binary.
- Infrastructure/Deployment:
- Docker configuration files (Dockerfile, .dockerignore) and GitHub workflows indicate containerized deployment and CI/CD practices.
- Environment variable configuration and a detailed table in the README show how the server is parameterized.

##### Relationships and Interactions
- Within the backend, the main server (als.go) routes requests to different controllers (for example, Ping, iPerf3, Speedtest, Shell). Represent these as subcomponents:
- Controller/Handlers: Each controller (e.g., “ping”, “iperf3”, “speedtest”, “shell”) acts as a service endpoint.
- Timer/Traffic: A module that periodically updates or monitors network traffic.
- Config and Environment: Loads settings (like port configuration, IP addresses) that influence the behavior of controllers.

##### Architectural Patterns
- Modular Design: The backend is split into well-organized packages (controllers, config, timer, embed), suggesting a clean separation of concerns.
- MVC-like Pattern: Although not a strict MVC, the controllers (handling HTTP routes) and separate config and service layers indicate some level of the pattern.
- Containerization: The presence of Docker files and GitHub actions workflows emphasizes that deployments should be container-based, so include a Docker container node encapsulating the entire application.
- External Dependency Management: Configuration via environment variables and external API calls (ipapi, ifconfig) are key in the design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend (Vue.js UI)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE["Backend API Server (Go)"]:::backend
        HS["HTTP Server Initialization & Routing"]:::backend
        conf["Configuration Loader"]:::module
        timer["Timer/Scheduler Module"]:::module
        embed["Embedded UI Assets"]:::module
        fakeShell["Fake Shell Module"]:::module
        subgraph "Controllers"
            ping["Ping Controller"]:::module
            iperf["iPerf3 Controller"]:::module
            shell["Shell Controller"]:::module
            speed["Speedtest Controller"]:::module
            cache["Cache Controller"]:::module
            session["Session Controller"]:::module
        end
    end

    %% Deployment Layer
    subgraph "Deployment"
        docker["Dockerfile"]:::deployment
        dockerignore[".dockerignore"]:::deployment
        cicd["CI/CD Workflows (.github/)"]:::deployment
    end

    %% External Dependencies
    ext["External IP/Geo Services"]:::external

    %% Connections between layers and components
    FE -->|"HTTP_Request"| HS
    HS -->|"Passes_Request"| BE
    BE -->|"Routes_to"| ping
    BE -->|"Routes_to"| iperf
    BE -->|"Routes_to"| shell
    BE -->|"Routes_to"| speed
    BE -->|"Routes_to"| cache
    BE -->|"Routes_to"| session
    BE -->|"Loads_Config"| conf
    BE -->|"Schedules"| timer
    BE -->|"Serves_Embedded"| embed
    BE -->|"Handles_FakeShell"| fakeShell
    embed -->|"Serves_UI"| FE
    ping -->|"Calls_External"| ext
    speed -->|"Calls_External"| ext
    FE -->|"Deployed_in"| docker
    BE -->|"Deployed_in"| docker

    %% Click Events
    click FE "https://github.com/wikihost-opensource/als/tree/master/ui/"
    click BE "https://github.com/wikihost-opensource/als/blob/master/backend/als/als.go"
    click HS "https://github.com/wikihost-opensource/als/blob/master/backend/http/init.go"
    click ping "https://github.com/wikihost-opensource/als/blob/master/backend/als/controller/ping/ping.go"
    click iperf "https://github.com/wikihost-opensource/als/blob/master/backend/als/controller/iperf3/iperf3.go"
    click shell "https://github.com/wikihost-opensource/als/blob/master/backend/als/controller/shell/shell.go"
    click speed "https://github.com/wikihost-opensource/als/tree/master/backend/als/controller/speedtest/"
    click cache "https://github.com/wikihost-opensource/als/blob/master/backend/als/controller/cache/interface.go"
    click session "https://github.com/wikihost-opensource/als/blob/master/backend/als/controller/session/session.go"
    click conf "https://github.com/wikihost-opensource/als/tree/master/backend/config/"
    click timer "https://github.com/wikihost-opensource/als/tree/master/backend/als/timer/"
    click embed "https://github.com/wikihost-opensource/als/tree/master/backend/embed/"
    click fakeShell "https://github.com/wikihost-opensource/als/tree/master/backend/fakeshell/"
    click docker "https://github.com/wikihost-opensource/als/tree/master/Dockerfile"
    click dockerignore "https://github.com/wikihost-opensource/als/blob/master/.dockerignore"
    click cicd "https://github.com/wikihost-opensource/als/tree/master/.github/"

    %% Styles
    classDef frontend fill:#b3e5fc,stroke:#0277bd,stroke-width:2px;
    classDef backend fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef module fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef external fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px;
    classDef deployment fill:#d1c4e9,stroke:#673ab7,stroke-width:2px;
```
