# ngoduykhanh/wireguard-ui architecture

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

- Interactive diagram: https://gitdiagram.com/ngoduykhanh/wireguard-ui
- Repository: https://github.com/ngoduykhanh/wireguard-ui

## Overview

##### Project Type and Purpose
- Project Type: It’s a full-stack web application (backed by a Go server) designed specifically for managing WireGuard configurations and client details.
- Purpose: Offering a friendly web UI that facilitates VPN client management, configuration distribution (via QR code, file, email, Telegram), and server settings customization.

##### File Structure
- Top-level Organization:
- Main Go server entry: main.go initializes the server.
- Directories such as “handler” (HTTP request handlers, routes, and session management), “router” (defining routing and validation), “model” (data models representing clients, servers, settings, etc.), “store” (data persistence using JSON-based storage), “emailer” (handling different email delivery methods), and “telegram” (Telegram bot integration).
- “templates” holds HTML templates for the web UI.
- “custom” and “assets” contain static assets like JS, images, and possibly CSS.
- “db” might represent the database configuration (or marker) and related ignore settings.
- “util” provides helper functions and configuration utilities.
- Supporting Files:
- Dockerfile, docker-compose.yaml, and example docker-compose setups highlight container deployment.
- Configuration and environment variable details in the README guide runtime behavior.
- Build scripts like “prepare_assets.sh” and continuous integration files under “.github” directory.

##### Architectural Insights from the README
- The README emphasizes managing WireGuard configuration, including handling logins, serving client configurations, and managing environment-related settings.
- It explains how to run the service both as a binary and within Docker using docker-compose.
- There are integration points for restarting the WireGuard daemon (via systemd or openrc) suggesting an operational flow outside of the core application for infrastructure management.

a. Main Components to Include:
- Client Browser / Frontend: Represents the user interface that interacts with the application.
- Web Server / Backend: A monolithic Go server that handles requests. Within this, illustrate submodules:
- Router & Handlers: Where routes, middlewares, and session management are defined.
- Business Logic and Models: Represented by the “model” package which structures client, server, and configuration data.
- Data Store: The persistence layer implemented in the “store” package (with the JSONDB module).
- Template Engine: Utilizes the “templates” folder to render dynamic HTML views.
- Static Assets: “assets” and “custom” directories for CSS, JavaScript, and images.
- External Services & Integrations:
- Email Service: The “emailer” module which supports SendGrid and SMTP for sending emails.
- Telegram Integration: The “telegram” module for optionally delivering config via Telegram.
- WireGuard Service: Although not managed directly by the application, the system interacts with the WireGuard configuration (as directed by generated configs and potential service restarts).
b. Relationships and Data Flow:
- User actions in the browser send HTTP requests to the Go server.
- The router dispatches these requests to the appropriate handlers.
- Handlers interact with the model and store to perform CRUD operations on client and server data.
- Depending on actions (e.g., “send config by email”), the system utilizes the emailer or telegram modules.
- The server generates or updates configuration files (using templates and util functions) which could then trigger external operations (like restarting WireGuard via Docker or systemd).
c. Architectural Patterns and Principles:
- MVC/Modular Structure: Although consolidated into a single service, the separation between routing, handling, and data persistence shows a clear modular approach.
- Configuration through Environment Variables: Emphasize how behavior is controlled via environment settings.
- Containerization: The Dockerfile and docker-compose setups illustrate deployment best practices.
d. Key Technologies & Frameworks:
- Go for the backend implementation.
- Docker for containerized deployments.
- SMTP and SendGrid for email delivery.
- Telegram Bot API for messaging.
- Standard HTML templating for the frontend.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        CB("Client Browser"):::frontend
        TE("Template Engine"):::frontend
        subgraph "Static Assets"
            AS("Assets"):::frontend
            CA("Custom Assets"):::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend Layer"
        WS("Web Server Entry"):::backend
        subgraph "Routing & Request Handling"
            H("HTTP Handlers"):::backend
            R("HTTP Router"):::backend
        end
        BL("Business Logic (Models)"):::backend
        DS("Data Store (JSONDB)"):::backend
        UT("Utilities & Config"):::backend
    end

    %% External Integrations
    subgraph "External Integrations"
        ES("Email Service"):::external
        TG("Telegram Integration"):::external
        WG("WireGuard Service"):::external
    end

    %% Connections
    CB -->|"sends request"| WS
    WS -->|"dispatches to"| H
    WS -->|"dispatches to"| R
    H -->|"processes request"| BL
    R -->|"validates request"| BL
    BL -->|"persists data"| DS
    BL -->|"uses"| UT
    H -->|"renders view"| TE
    TE -->|"delivers HTML"| CB
    BL -->|"triggers"| WG
    BL -->|"notifies"| ES
    BL -->|"notifies"| TG

    %% Styles
    classDef frontend fill:#66ccff,stroke:#333,stroke-width:2px;
    classDef backend fill:#ffcc66,stroke:#333,stroke-width:2px;
    classDef external fill:#ccff99,stroke:#333,stroke-width:2px;

    %% Click Events
    click WS "https://github.com/ngoduykhanh/wireguard-ui/blob/master/main.go"
    click H "https://github.com/ngoduykhanh/wireguard-ui/tree/master/handler/"
    click R "https://github.com/ngoduykhanh/wireguard-ui/tree/master/router/"
    click BL "https://github.com/ngoduykhanh/wireguard-ui/tree/master/model/"
    click DS "https://github.com/ngoduykhanh/wireguard-ui/tree/master/store/"
    click TE "https://github.com/ngoduykhanh/wireguard-ui/tree/master/templates/"
    click AS "https://github.com/ngoduykhanh/wireguard-ui/tree/master/assets/"
    click CA "https://github.com/ngoduykhanh/wireguard-ui/tree/master/custom/"
    click ES "https://github.com/ngoduykhanh/wireguard-ui/tree/master/emailer/"
    click TG "https://github.com/ngoduykhanh/wireguard-ui/tree/master/telegram/"
    click UT "https://github.com/ngoduykhanh/wireguard-ui/tree/master/util/"
```
