# samwafgo/samwaf architecture

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

- Interactive diagram: https://gitdiagram.com/samwafgo/samwaf
- Repository: https://github.com/samwafgo/samwaf

## Overview

##### Main high-level components
- User Interface: Represented by the “vue” folder (and public UI assets), which provides the web-based dashboard and configuration pages.
- API/Controller Layer: The “api”, “router”, and “middleware” directories contain RESTful endpoints and authentication/security middleware. They serve as the entry points for administrative and monitoring operations.
- Core WAF Engine: The “wafenginecore” folder (along with supporting modules in “wafproxy”, “wafqueue”, “waftask”, “wafinit”, etc.) represents the engine that performs request inspection, rule checking, load balancing, and other security logic.
- Configuration & Rules Management: The “conf”, “model”, “customtype”, “enums”, and “codetemplete” directories store configuration files, definitions of rules, and templates for generating or updating rules.
- Data Persistence and Logging: The “wafdb”, “model”, and “cache” directories point to how the project manages logs, attack records, and configuration data. This component can also include encrypted log storage features described in the README.
- Notification and External Integrations: The “wafnotify” directory (with subfolders for Kafka and RabbitMQ) and “utils/wechat” indicate channels for sending alerts and integration with external messaging systems.
- Auxiliary Tools: Other directories (like “wafbot”, “wafsec”, “wafowasp”, “wafupdate”) represent specialized functions such as bot detection, encryption utilities, and rule updates.
- Deployment & Build Infrastructure: The Dockerfile, “docker-compose.yml”, and CI/CD related directories (.github, .gitea) illustrate the build, release, and container orchestration aspects.

##### Relationships and interactions
- Incoming web traffic first reaches the deployed WAF; requests are intercepted and processed by the core engine (wafenginecore) via modules in “wafproxy” and “middleware”.
- The API layer (“api” and “router”) exposes administrative functions and collects data (attack logs, system status) from the engine.
- The Web UI (in “vue”) communicates with these APIs to display the management dashboard, configuration screens, and report logs/alerts.
- The engine uses configuration data (loaded from “conf” and “model”) and applies security rules for filtering and blocking malicious requests.
- Logs and events are stored in local databases (managed by “wafdb”) while also being processed for notifications through the “wafnotify” module.
- There are also scheduled tasks and background workers (under “waftask” and “wafqueue”) ensuring periodic operations like SSL certificate checks, cache updates, and system health monitoring.

##### Architectural patterns/design principles
- Separation of concerns: The system is clearly divided between the presentation layer (Vue-based UI), the API layer (controllers/middleware), the core WAF logic (wafenginecore and related modules), and persistence/logging.
- Modular design: With distinct folders for features (e.g., security rule processing, caching, notifications), the project encourages extension and isolation of concerns.
- Microservice/Cross-module communication: Even though it is a single project, components like wafnotify, waftask, and the database interactions indicate a loosely coupled structure where different subsystems interact via well-defined interfaces.
- Cross-platform deployment: Support for Windows, Linux, and containerized deployment (Dockerfiles and Compose scripts) is evident.

##### Relevant technologies/frameworks and libraries
- Programming Language: Go is used across the project.
- Web Framework: Likely using Gin (indicated by “middleware/gin_global_exception_middleware.go”) for handling HTTP requests.
- Frontend: A Vue-based front end is provided.
- Messaging: Kafka and RabbitMQ integrations are visible.
- Database: Interaction with local databases (using GORM, as seen in “wafdb/gormlogger.go”).
- Other libraries: libinjection-go for injection detection, and various utility libraries for encryption, logging, and HTTP handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        UI["Vue Web Dashboard"]:::client
    end

    %% API/Middleware Layer
    subgraph "API/Middleware Layer"
        API["API Endpoints"]:::api
        Router["Router Layer"]:::api
        Middleware["Security Middleware"]:::api
    end

    %% Core WAF Engine
    subgraph "Core WAF Engine"
        Engine["WAF Engine Core"]:::core
        Proxy["Proxy/Content Inspection"]:::core
        Task["Task Scheduler"]:::core
        Init["Initialization Module"]:::core
        Engine --> Proxy
        Engine --> Task
        Engine --> Init
    end

    %% Configuration & Rules Management
    subgraph "Configuration & Rules Management"
        Config["Configuration Files"]:::config
        Templates["Rule Templates"]:::config
    end

    %% Data Persistence and Logging
    subgraph "Data Persistence and Logging"
        DB[(Database/Log Storage)]:::data
        Cache["Cache Mechanism"]:::data
        Models["Data Models"]:::data
    end

    %% Notification & Messaging
    subgraph "Notification & Messaging"
        Notify["Notification Services"]:::notify
        WeChat["WeChat Integration"]:::notify
    end

    %% Auxiliary Tools
    subgraph "Auxiliary Tools"
        Bot["WAF Bot"]:::aux
        SecTool["WAF Security"]:::aux
        OWASP["WAF OWASP"]:::aux
        Update["WAF Update"]:::aux
    end

    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure"
        Docker["Dockerfile"]:::deploy
        Compose["Docker Compose"]:::deploy
        GitHub["CI/CD Config (GitHub)"]:::deploy
        Gitea["CI/CD Config (Gitea)"]:::deploy
    end

    %% Relationships
    UI -->|"sendsRequests"| API
    UI -->|"sendsRequests"| Router
    UI -->|"sendsRequests"| Middleware

    API -->|"sendsTo"| Engine
    Router -->|"routesTo"| Engine
    Middleware -->|"secures"| Engine

    Config -->|"loadRules"| Engine
    Templates -->|"loadRules"| Engine

    Engine -->|"logs"| DB
    DB -->|"displayData"| UI

    Engine -->|"alerts"| Notify
    Notify -->|"notifyVia"| WeChat

    Engine -->|"integrates"| Bot
    Engine -->|"integrates"| SecTool
    Engine -->|"integrates"| OWASP
    Engine -->|"integrates"| Update

    Docker ---|"deploys"| Engine
    Compose ---|"deploys"| Engine
    GitHub ---|"deploys"| Engine
    Gitea ---|"deploys"| Engine

    %% Click Events
    click UI "https://github.com/samwafgo/samwaf/blob/main/vue/dist/index.html"
    click API "https://github.com/samwafgo/samwaf/tree/main/api/"
    click Router "https://github.com/samwafgo/samwaf/tree/main/router/"
    click Middleware "https://github.com/samwafgo/samwaf/tree/main/middleware/"
    click Engine "https://github.com/samwafgo/samwaf/tree/main/wafenginecore"
    click Proxy "https://github.com/samwafgo/samwaf/tree/main/wafproxy"
    click Task "https://github.com/samwafgo/samwaf/tree/main/waftask"
    click Init "https://github.com/samwafgo/samwaf/tree/main/wafinit"
    click Config "https://github.com/samwafgo/samwaf/blob/main/conf/config.yml"
    click Templates "https://github.com/samwafgo/samwaf/tree/main/codetemplete"
    click DB "https://github.com/samwafgo/samwaf/blob/main/wafdb/gormlogger.go"
    click Cache "https://github.com/samwafgo/samwaf/tree/main/cache/"
    click Models "https://github.com/samwafgo/samwaf/tree/main/model/"
    click Notify "https://github.com/samwafgo/samwaf/blob/main/wafnotify/wafnotify.go"
    click WeChat "https://github.com/samwafgo/samwaf/tree/main/utils/wechat/"
    click Bot "https://github.com/samwafgo/samwaf/tree/main/wafbot/"
    click SecTool "https://github.com/samwafgo/samwaf/tree/main/wafsec/"
    click OWASP "https://github.com/samwafgo/samwaf/tree/main/wafowasp/"
    click Update "https://github.com/samwafgo/samwaf/tree/main/wafupdate/"
    click Docker "https://github.com/samwafgo/samwaf/tree/main/Dockerfile"
    click Compose "https://github.com/samwafgo/samwaf/blob/main/docker-compose.yml"
    click GitHub "https://github.com/samwafgo/samwaf/tree/main/.github/"
    click Gitea "https://github.com/samwafgo/samwaf/tree/main/.gitea/"

    %% Styles
    classDef client fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef core fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef config fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef data fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef notify fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef aux fill:#fefefe,stroke:#6c757d,stroke-width:2px;
    classDef deploy fill:#e6ccff,stroke:#6f42c1,stroke-width:2px;
```
