# wifidog/wifidog-gateway architecture

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

- Interactive diagram: https://gitdiagram.com/wifidog/wifidog-gateway
- Repository: https://github.com/wifidog/wifidog-gateway

## Overview

##### Project type and purpose
- This is the WiFiDog Gateway: an embedded, C-based captive-portal client/daemon that runs on a wireless gateway device.
- Its purpose is to intercept and redirect HTTP requests from end-users to a remote auth server, enforce firewall rules (via iptables), maintain client state, and lift restrictions once users authenticate.

##### File structure
- Top level: autotools files (configure.in, Makefile.am, autogen.sh), packaging & contrib scripts, documentation.
- libhttpd/: a small HTTP server library used by the gateway.
- src/: core gateway logic, organized into modules (auth, centralserver, client_list, firewall, http/httpd_thread, configuration, threads, utilities, wdctl control interface).
- contrib/: build recipes for Debian/OpenWRT, load-testing tools, sample init scripts.

##### README for additional insights
- The client daemon (“gateway”) implements WifiDog Protocol v1, offloading authentication to a separate auth server.
- It listens on the LAN side, redirects unauthenticated users to the auth server, polls the auth server (ping thread) for session status, and updates netfilter rules accordingly.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    EndUsers["End User Devices"]:::external
    Internet["Internet"]:::external
    AuthServer["Remote Auth Server"]:::external

    %% Gateway Daemon Container
    subgraph "Gateway Daemon"
        style GatewayDaemon stroke:#333,stroke-width:2px
        MainEntry["Main Entry (main.c/gateway.c)"]:::module
        ConfigLoader["Configuration Loader\n(conf.c/commandline.c)"]:::module
        NetworkFilter["Network Filter Module\n(fw_iptables.c/firewall.c)"]:::filter
        EmbeddedHTTPD["Embedded HTTPD\n(libhttpd/httpd_thread.c/simple_http.c/http.c)"]:::module
        AuthHandler["Auth Protocol Handler\n(auth.c/centralserver.c)"]:::module
        ClientState["Client State Manager\n(client_list.c)"]:::module
        ControlInterface["Control Interface\n(wdctl.c/wdctl_thread.c)"]:::module
        BackgroundWorkers["Background Workers\n(ping_thread.c/util.c/wd_util.c)"]:::module
    end

    %% Flow Connections
    EndUsers -->|"HTTP GET /login"| NetworkFilter
    NetworkFilter -->|"redirect to HTTPD"| EmbeddedHTTPD
    EmbeddedHTTPD -->|"login request"| AuthHandler
    AuthHandler -->|"HTTP ping/login"| AuthServer
    AuthServer -->|"session status"| AuthHandler
    AuthHandler -->|"update client state"| ClientState
    AuthHandler -->|"open/close rules"| NetworkFilter
    ClientState -->|"state data"| BackgroundWorkers
    BackgroundWorkers -->|"periodic ping"| AuthHandler
    EmbeddedHTTPD -->|"serve portal pages"| EndUsers
    AuthHandler -->|"post-auth traffic"| Internet
    ControlInterface -->|"commands"| MainEntry
    ConfigLoader --> MainEntry
    MainEntry --> NetworkFilter
    MainEntry --> EmbeddedHTTPD
    MainEntry --> AuthHandler
    MainEntry --> ClientState
    MainEntry --> ControlInterface
    MainEntry --> BackgroundWorkers

    %% Click Events
    click MainEntry "https://github.com/wifidog/wifidog-gateway/blob/master/src/main.c"
    click ConfigLoader "https://github.com/wifidog/wifidog-gateway/blob/master/src/conf.c"
    click NetworkFilter "https://github.com/wifidog/wifidog-gateway/blob/master/src/fw_iptables.c"
    click EmbeddedHTTPD "https://github.com/wifidog/wifidog-gateway/tree/master/libhttpd/"
    click AuthHandler "https://github.com/wifidog/wifidog-gateway/blob/master/src/auth.c"
    click ClientState "https://github.com/wifidog/wifidog-gateway/blob/master/src/client_list.c"
    click ControlInterface "https://github.com/wifidog/wifidog-gateway/blob/master/src/wdctl.c"
    click BackgroundWorkers "https://github.com/wifidog/wifidog-gateway/blob/master/src/ping_thread.c"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef module fill:#90EE90,stroke:#000,stroke-width:1px
    classDef filter fill:#FFA500,stroke:#000,stroke-width:1px
```
