# liudf0716/wwas architecture

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

## Overview

##### Project Overview and Purpose
- This is a Node.js–based authentication server designed to support both the apfree wifidog and the traditional wifidog protocol. Its goal is to authenticate clients connecting through WiFi hotspots (often configured on OpenWRT devices) so that the WiFi portal, UI, and other components can provide controlled access.
- The server interacts with components like MongoDB (for persistent storage), Redis (for caching and pub/sub notifications), and external WiFi gateway devices that forward authentication requests.

##### Main Components
a. Core Application Server
- Entry Points: The app.js and index.js files kick off the server.
- Configuration: The config directory (with files such as default.js and development.js) shows environment-specific settings.
- Routing: The routes folder groups endpoints for various functions (admin, client, device, setting, wifidog).
- Controllers: Under the controller directory, modules further divide into admin, client, device, setting, and wifidog. These modules are responsible for handling business logic for their respective domains.
- Models: The models folder reflects a clear separation based on domain (admin, client, device, setting, wifidog), suggesting an MVC-style architecture where data interaction is abstracted.
- Middlewares: Custom middleware (e.g., check.js in the middlewares folder) handles pre-processing tasks like authentication or request validation.

b. Static Assets and Views
- Public Assets: The public directory contains static resources (CSS, JavaScript, images) for the user interface. This might be used for login screens or portal visuals.
- View Templates: The views folder, which includes at least a login.html file, is used for server-rendered UI elements.

c. External Dependencies
- MongoDB: Referenced in the mongodb/db.js file; it is used by the models for persistent storage.
- Redis: Although not present as source code here, the README details installation and configuration instructions, so include it as an external caching and pub/sub component.
- The WiFi Gateway (Apfree/wifidog): Represent external WiFi devices (via OpenWRT configuration) that interact with this auth server. Their configuration (provided in the README) points to this server’s endpoint.

##### Relationships and Data Flow
- Incoming requests from the WiFi gateways or client browsers hit the Node.js server through the defined routes.
- Routes delegate requests to appropriate controllers based on the feature area (admin, device, client, etc.).
- Controllers interface with models to interact with MongoDB for data storage and may also trigger operations that involve Redis (e.g., notifications).
- Static files are served directly from the public folder, and view templates (e.g., login.html) are rendered as needed.
- The configuration files drive environment-specific behaviors, ensuring smooth operation across development and production.

##### Architectural Patterns Highlighted
- Emphasis on separation of concerns (controllers, models, routes) following an MVC or layered architectural pattern.
- Use of configuration management (via the config folder) to support multiple environments.
- Integration of external services like MongoDB and Redis that complement the core Node.js server.
- The UI and static assets separation supports a basic full-stack design where the backend serves dynamic content alongside static resources.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "wificoin-wifidog-auth-server (Node.js App)"
        %% API Entry Points
        subgraph "API Entry Points"
            A1("app.js"):::code
            A2("index.js"):::code
        end

        %% Configuration
        subgraph "Configuration"
            C1("default.js"):::code
            C2("development.js"):::code
        end

        %% Routing
        subgraph "Routing"
            R1("admin.js"):::code
            R2("client.js"):::code
            R3("device.js"):::code
            R4("setting.js"):::code
            R5("wifidog.js"):::code
            R6("index.js (routes)"):::code
        end

        %% Controllers
        subgraph "Controllers"
            CT1("admin.js"):::code
            CT2("client.js"):::code
            CT3("device.js"):::code
            CT4("setting.js"):::code
            CT5("wifidog.js"):::code
        end

        %% Models
        subgraph "Models"
            M1("admin.js"):::code
            M2("client.js"):::code
            M3("device.js"):::code
            M4("channelpath.js"):::code
            M5("gatewayid.js"):::code
            M6("token.js"):::code
            M7("wfcorder.js"):::code
        end

       %% Middlewares
       subgraph "Middlewares"
           MD("check.js"):::code
       end

       %% Static Assets and Views
       subgraph "Static Assets & Views"
            SA("public (Static Assets)"):::asset
            VT("login.html"):::asset
       end
    end

    %% External Services
    DB("MongoDB"):::external
    RDS("Redis"):::external
    WG("WiFi Gateway Devices"):::external

    %% External Request Flow
    WG -->|"auth_request"| A1
    WG -->|"auth_request"| A2

    %% Internal Flow: Entry Points to Routing
    A1 -->|"routes"| R6
    A2 -->|"routes"| R6

    %% Routing delegates to Controllers
    R6 -->|"delegates_to"| R1
    R6 -->|"delegates_to"| R2
    R6 -->|"delegates_to"| R3
    R6 -->|"delegates_to"| R4
    R6 -->|"delegates_to"| R5

    %% Controllers Handling
    R1 -->|"calls"| CT1
    R2 -->|"calls"| CT2
    R3 -->|"calls"| CT3
    R4 -->|"calls"| CT4
    R5 -->|"calls"| CT5

    %% Controllers interact with Models
    CT1 -->|"uses"| M1
    CT2 -->|"uses"| M2
    CT3 -->|"uses"| M3
    CT4 -->|"uses"| M4
    CT4 -->|"uses"| M5
    CT5 -->|"uses"| M6
    CT5 -->|"uses"| M7

    %% Models persist data to MongoDB
    M1 -->|"persists"| DB
    M2 -->|"persists"| DB
    M3 -->|"persists"| DB
    M4 -->|"persists"| DB
    M5 -->|"persists"| DB
    M6 -->|"persists"| DB
    M7 -->|"persists"| DB

    %% Controllers use Redis for caching/notifications
    CT1 ---|"notify"| RDS
    CT2 ---|"notify"| RDS
    CT3 ---|"notify"| RDS
    CT4 ---|"notify"| RDS
    CT5 ---|"notify"| RDS

    %% Server serves static and view assets
    A2 -->|"serves"| SA
    A2 -->|"renders"| VT

    %% Entry Points use Configuration and Middlewares
    A2 -->|"configures"| C1
    A2 -->|"configures"| C2
    A2 -->|"applies"| MD

    %% Click Events for Entry Points
    click A1 "https://github.com/liudf0716/wwas/blob/master/app.js"
    click A2 "https://github.com/liudf0716/wwas/blob/master/index.js"

    %% Click Events for Configuration
    click C1 "https://github.com/liudf0716/wwas/blob/master/config/default.js"
    click C2 "https://github.com/liudf0716/wwas/blob/master/config/development.js"

    %% Click Events for Routing
    click R1 "https://github.com/liudf0716/wwas/blob/master/routes/admin.js"
    click R2 "https://github.com/liudf0716/wwas/blob/master/routes/client.js"
    click R3 "https://github.com/liudf0716/wwas/blob/master/routes/device.js"
    click R4 "https://github.com/liudf0716/wwas/blob/master/routes/setting.js"
    click R5 "https://github.com/liudf0716/wwas/blob/master/routes/wifidog.js"
    click R6 "https://github.com/liudf0716/wwas/blob/master/routes/index.js"

    %% Click Events for Controllers
    click CT1 "https://github.com/liudf0716/wwas/blob/master/controller/admin/admin.js"
    click CT2 "https://github.com/liudf0716/wwas/blob/master/controller/client/client.js"
    click CT3 "https://github.com/liudf0716/wwas/blob/master/controller/device/device.js"
    click CT4 "https://github.com/liudf0716/wwas/blob/master/controller/setting/setting.js"
    click CT5 "https://github.com/liudf0716/wwas/blob/master/controller/wifidog/wifidog.js"

    %% Click Events for Models
    click M1 "https://github.com/liudf0716/wwas/blob/master/models/admin/admin.js"
    click M2 "https://github.com/liudf0716/wwas/blob/master/models/client/client.js"
    click M3 "https://github.com/liudf0716/wwas/blob/master/models/device/device.js"
    click M4 "https://github.com/liudf0716/wwas/blob/master/models/setting/channelpath.js"
    click M5 "https://github.com/liudf0716/wwas/blob/master/models/setting/gatewayid.js"
    click M6 "https://github.com/liudf0716/wwas/blob/master/models/wifidog/token.js"
    click M7 "https://github.com/liudf0716/wwas/blob/master/models/wifidog/wfcorder.js"

    %% Click Events for Middlewares
    click MD "https://github.com/liudf0716/wwas/blob/master/middlewares/check.js"

    %% Click Events for Static Assets & Views
    click SA "https://github.com/liudf0716/wwas/tree/master/public"
    click VT "https://github.com/liudf0716/wwas/blob/master/views/login.html"

    %% Click Event for MongoDB Connection
    click DB "https://github.com/liudf0716/wwas/blob/master/mongodb/db.js"

    %% Styles
    classDef code fill:#f9f,stroke:#333,stroke-width:2px;
    classDef asset fill:#bbf,stroke:#333,stroke-width:2px;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px;
```
