# leonovk/wg-rest-api architecture

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

- Interactive diagram: https://gitdiagram.com/leonovk/wg-rest-api
- Repository: https://github.com/leonovk/wg-rest-api

## Overview

##### Project Type and Purpose
- This is an open-source, Docker-packaged REST API service (written in Ruby) for managing a WireGuard VPN server.
- It exposes HTTP endpoints to create/list/update/delete WireGuard clients, read server stats, generate QR codes/configs, and send webhooks on client connect/disconnect events.

##### File Structure
- Top-level files: Dockerfile, config.ru (Rack entry), app.rb (Sinatra/Grape-style endpoints).
- app/api: HTTP controllers, serializers, validators under two namespaces: /api/clients and /api/server.
- lib/wire_guard: service objects for key generation, config building/updating, stat parsing.
- lib/utils & lib/webhooks: QR‐code and config‐file builders, webhook aggregation and sending.
- config: environment settings, Puma, Sentry, dependency wiring.
- bin/wgpass: CLI tool to generate hashed tokens.
- tasks/*.rake: operational Rake tasks (backups, stats, events).
- spec/: comprehensive test coverage (controllers, serializers, service objects).
- No database—configuration is persisted directly as WireGuard files on the host filesystem under /etc/wireguard (bind-mounted via Docker).

##### README for Additional Insights
- Service runs single-threaded Puma (configurable threads/workers, but not thread-safe).
- Auth via bearer token or SHA256 hash.
- Exposes health check, client CRUD, format variations (QR/png or .conf), and server stats.
- Webhook notifications are optional “beta” feature.
- Deployment expected via Docker with NET_ADMIN capability.

##### Don’t Overthink—Capture All Essential Elements
- How they connect under the Docker container boundary.
- Be explicit about volumes (/etc/wireguard) and kernel calls (wireguard-tools).
- Clearly distinguish synchronous flows (API requests) from asynchronous/outbound flows (webhooks, Rake tasks, Sentry).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    HTTP_Client["HTTP Client"]:::external
    %% Docker Container Boundary
    subgraph "Docker Container"
        direction TB
        Dockerfile["Dockerfile"]:::config
        ConfigRU["config.ru"]:::api
        AppRB["app.rb"]:::api
        AuthM["Auth Middleware"]:::api

        subgraph "API Layer"
            direction TB
            ClientsController["ClientsController"]:::api
            ClientsSerializer["ClientsSerializer"]:::api
            ClientsValidator["ClientsValidator"]:::api
            ServerController["ServerController"]:::api
            ServerSerializer["ServerSerializer"]:::api
        end

        subgraph "Business Logic"
            direction TB
            subgraph "WireGuard Services"
                direction TB
                KeyGen["KeyGenerator"]:::logic
                ClientCfgBuilder["ClientConfigBuilder"]:::logic
                ServerCfgUpdater["ServerConfigUpdater"]:::logic
                ServerStatModel["ServerStat"]:::logic
                StatParser["StatParser"]:::logic
                StatGen["StatGenerator"]:::logic
                ServerFacade["ServerFacade"]:::logic
            end
            subgraph "Utility Builders"
                direction TB
                ConfigFileBuilder["ConfigFileBuilder"]:::logic
                QRCodeBuilder["QRCodeBuilder"]:::logic
            end
            subgraph "Webhooks"
                direction TB
                WG_Aggregator["Aggregator"]:::logic
                WG_Events["Events"]:::logic
                WG_Sender["Sender"]:::logic
                WG_Client["Client Wrapper"]:::logic
            end
        end

        subgraph "Config & Settings"
            direction TB
            AppConfig["application.rb"]:::config
            ConfigRB["config.rb"]:::config
            Dependencies["dependencies.rb"]:::config
            PumaCfg["puma.rb"]:::config
            SentryCfg["sentry.rb"]:::config
            SettingsDEV["development.yaml"]:::config
            SettingsPROD["production.yaml"]:::config
            SettingsTEST["test.yaml"]:::config
        end

        subgraph "Rake Tasks"
            direction TB
            ClearStats["clear_stats.rake"]:::tasks
            CreateBackup["create_backup.rake"]:::tasks
            RestoreBackup["restore_from_backup.rake"]:::tasks
            SendEventsTask["send_events.rake"]:::tasks
            ShowVersions["show_versions.rake"]:::tasks
            Bump["dev/bump.rake"]:::tasks
            BumpMinor["dev/bump_minor.rake"]:::tasks
        end

        CLI["wgpass CLI"]:::cli
        Volume["/etc/wireguard Volume"]:::system
        Kernel["WireGuard CLI & Kernel Module"]:::system
    end

    %% External Services
    WebhookEP["Webhook Endpoints"]:::external
    Sentry["Sentry"]:::external

    %% Connections
    HTTP_Client -->|"HTTP Request"| ConfigRU
    ConfigRU -->|"Rack Routing"| AppRB
    AppRB --> AuthM
    AuthM --> ClientsController
    AuthM --> ServerController

    ClientsController --> ClientsValidator
    ClientsController --> KeyGen
    ClientsController --> ClientCfgBuilder
    ClientsController --> ConfigFileBuilder
    ClientsController --> QRCodeBuilder
    ClientsController --> ClientsSerializer

    ServerController --> StatParser
    ServerController --> StatGen
    ServerController --> ServerStatModel
    ServerController --> ServerCfgUpdater
    ServerController --> ServerSerializer

    KeyGen --> Volume
    ClientCfgBuilder --> Volume
    ServerCfgUpdater --> Volume
    ServerCfgUpdater --> Kernel
    StatParser --> Kernel
    StatParser --> Volume
    StatGen --> ServerStatModel

    ClientCfgBuilder --> WG_Events
    WG_Events --> WG_Aggregator
    WG_Aggregator --> WG_Sender
    WG_Sender --> WebhookEP

    %% Rake tasks reuse business logic
    ClearStats --> StatParser
    CreateBackup --> ServerCfgUpdater
    RestoreBackup --> ServerCfgUpdater
    SendEventsTask --> WG_Sender
    ShowVersions --> ServerFacade
    Bump --> AppRB
    BumpMinor --> AppRB

    %% CLI
    CLI --> Dependencies
    %% Config & Settings wiring
    AuthM --> Dependencies
    AuthM --> SettingsDEV
    AuthM --> SettingsPROD
    AuthM --> SettingsTEST

    %% Error Reporting
    ClientsController -->|error| Sentry
    ServerController -->|error| Sentry
    StatParser -->|error| Sentry
    WG_Sender -->|error| Sentry

    %% Click Events
    click Dockerfile "https://github.com/leonovk/wg-rest-api/tree/master/Dockerfile"
    click ConfigRU "https://github.com/leonovk/wg-rest-api/blob/master/config.ru"
    click AppRB "https://github.com/leonovk/wg-rest-api/blob/master/app.rb"
    click AuthM "https://github.com/leonovk/wg-rest-api/blob/master/config/dependencies.rb"
    click ClientsController "https://github.com/leonovk/wg-rest-api/blob/master/app/api/clients/controller.rb"
    click ClientsSerializer "https://github.com/leonovk/wg-rest-api/blob/master/app/api/clients/serializer.rb"
    click ClientsValidator "https://github.com/leonovk/wg-rest-api/blob/master/app/api/clients/validator.rb"
    click ServerController "https://github.com/leonovk/wg-rest-api/blob/master/app/api/server/controller.rb"
    click ServerSerializer "https://github.com/leonovk/wg-rest-api/blob/master/app/api/server/serializer.rb"
    click KeyGen "https://github.com/leonovk/wg-rest-api/blob/master/lib/wire_guard/key_generator.rb"
    click ClientCfgBuilder "https://github.com/leonovk/wg-rest-api/blob/master/lib/wire_guard/client_config_builder.rb"
    click ServerCfgUpdater "https://github.com/leonovk/wg-rest-api/blob/master/lib/wire_guard/server_config_updater.rb"
    click ServerStatModel "https://github.com/leonovk/wg-rest-api/blob/master/lib/wire_guard/server_stat.rb"
    click StatParser "https://github.com/leonovk/wg-rest-api/blob/master/lib/wire_guard/stat_parser.rb"
    click StatGen "https://github.com/leonovk/wg-rest-api/blob/master/lib/wire_guard/stat_generator.rb"
    click ServerFacade "https://github.com/leonovk/wg-rest-api/blob/master/lib/wire_guard/server.rb"
    click ConfigFileBuilder "https://github.com/leonovk/wg-rest-api/blob/master/lib/utils/config_file_builder.rb"
    click QRCodeBuilder "https://github.com/leonovk/wg-rest-api/blob/master/lib/utils/qr_code_builder.rb"
    click WG_Aggregator "https://github.com/leonovk/wg-rest-api/blob/master/lib/webhooks/aggregator.rb"
    click WG_Events "https://github.com/leonovk/wg-rest-api/blob/master/lib/webhooks/events.rb"
    click WG_Sender "https://github.com/leonovk/wg-rest-api/blob/master/lib/webhooks/sender.rb"
    click WG_Client "https://github.com/leonovk/wg-rest-api/blob/master/lib/webhooks/client.rb"
    click AppConfig "https://github.com/leonovk/wg-rest-api/blob/master/config/application.rb"
    click ConfigRB "https://github.com/leonovk/wg-rest-api/blob/master/config/config.rb"
    click Dependencies "https://github.com/leonovk/wg-rest-api/blob/master/config/dependencies.rb"
    click PumaCfg "https://github.com/leonovk/wg-rest-api/blob/master/config/puma.rb"
    click SentryCfg "https://github.com/leonovk/wg-rest-api/blob/master/config/sentry.rb"
    click SettingsDEV "https://github.com/leonovk/wg-rest-api/blob/master/config/settings/development.yaml"
    click SettingsPROD "https://github.com/leonovk/wg-rest-api/blob/master/config/settings/production.yaml"
    click SettingsTEST "https://github.com/leonovk/wg-rest-api/blob/master/config/settings/test.yaml"
    click ClearStats "https://github.com/leonovk/wg-rest-api/blob/master/tasks/clear_stats.rake"
    click CreateBackup "https://github.com/leonovk/wg-rest-api/blob/master/tasks/create_backup.rake"
    click RestoreBackup "https://github.com/leonovk/wg-rest-api/blob/master/tasks/restore_from_backup.rake"
    click SendEventsTask "https://github.com/leonovk/wg-rest-api/blob/master/tasks/send_events.rake"
    click ShowVersions "https://github.com/leonovk/wg-rest-api/blob/master/tasks/show_versions.rake"
    click Bump "https://github.com/leonovk/wg-rest-api/blob/master/tasks/dev/bump.rake"
    click BumpMinor "https://github.com/leonovk/wg-rest-api/blob/master/tasks/dev/bump_minor.rake"
    click CLI "https://github.com/leonovk/wg-rest-api/tree/master/bin/wgpass"

    %% Styles
    classDef api fill:#bbdefb,stroke:#1976d2,stroke-width:1px
    classDef logic fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef system fill:#e0e0e0,stroke:#757575,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#f57c00,stroke-width:1px
    classDef config fill:#fff9c4,stroke:#f9a825,stroke-width:1px
    classDef tasks fill:#f0f4c3,stroke:#afb42b,stroke-width:1px
    classDef cli fill:#d1c4e9,stroke:#7e57c2,stroke-width:1px
```
