From 455f0ed99d80fe6aa82bf8de0672b0a8db7c2a2c Mon Sep 17 00:00:00 2001 From: Alexander Moisseev Date: Thu, 1 Jan 2026 16:14:03 +0300 Subject: [PATCH] [Minor] Add WebUI architecture documentation Create interface/ARCHITECTURE.md to help developers and AI agents navigate the codebase. --- interface/ARCHITECTURE.md | 218 ++++++++++++++++++++++++++++++++++++++ interface/README.md | 7 ++ 2 files changed, 225 insertions(+) create mode 100644 interface/ARCHITECTURE.md diff --git a/interface/ARCHITECTURE.md b/interface/ARCHITECTURE.md new file mode 100644 index 0000000000..6f338e316a --- /dev/null +++ b/interface/ARCHITECTURE.md @@ -0,0 +1,218 @@ +# Rspamd WebUI Architecture + +## Overview + +The Rspamd WebUI is a single-page application (SPA) providing a web interface for monitoring and managing Rspamd. It communicates with Rspamd's Controller API and supports multiple server instances. + +**Main capabilities:** +- Real-time statistics and throughput monitoring +- Message processing history inspection +- Message scanning and analysis +- Bayes classifier and Fuzzy storage training +- Symbol and action configuration +- Map editing +- Selector testing +- Multi-server management + +## Technology Stack + +### Module System +- **RequireJS** - AMD (Asynchronous Module Definition) pattern for modular code organization + +### Core Libraries +- **jQuery** - DOM manipulation, event handling, AJAX +- **Bootstrap** - UI framework for responsive layout and components + +### Visualization & Data Display +- **D3.js** - Base visualization library +- **D3Evolution** - Time-series line charts (throughput graphs) +- **D3Pie** - Pie charts (action distribution) +- **FooTable** - Responsive data tables with sorting, filtering, and pagination + +### Code Editing +- **CodeJar** - Lightweight code editor +- **CodeJar Line Numbers** - Line numbering extension for CodeJar +- **Prism.js** - Syntax highlighting + +### Utilities +- **NProgress** - Progress bars for async operations +- **Visibility.js** - Page Visibility API wrapper for timer management +- **Font Awesome** - Icon library +- **jQuery Sticky Tabs** - Persistent tab state via URL hash + +### Theme System +Custom implementation supporting light/dark/auto modes with system preference detection. + +## Project Structure + +``` +interface/ +├── index.html # Main HTML file with tab structure +├── css/ # Stylesheets +│ ├── bootstrap.min.css +│ ├── rspamd.css # Custom styles +│ └── ... # Third-party CSS +├── js/ +│ ├── main.js # Entry point & RequireJS configuration +│ ├── app/ # Application modules +│ │ ├── common.js # Shared utilities and API client +│ │ ├── rspamd.js # Main application logic, auth, tab management +│ │ ├── stats.js # Statistics tab (status widgets) +│ │ ├── history.js # History tab (message log, errors) +│ │ ├── graph.js # Throughput tab (time-series graphs) +│ │ ├── symbols.js # Symbols tab (symbol scores editing) +│ │ ├── config.js # Configuration tab (actions, maps) +│ │ ├── upload.js # Scan tab (message upload/scanning) +│ │ ├── selectors.js # Selectors tab (testing selectors) +│ │ ├── libft.js # FooTable utilities (history table rendering) +│ │ └── footable-fontawesome.js # FooTable Font Awesome integration +│ └── lib/ # Third-party libraries (minified) +├── img/ # Images and logos +└── README.md # Setup instructions +``` + +## Module System + +The WebUI uses **RequireJS** (AMD pattern) for modular code organization. + +**Module definition pattern:** +```javascript +define(["dependency1", "dependency2"], (dep1, dep2) => { + const ui = {}; + ui.publicMethod = function() { /* ... */ }; + return ui; +}); +``` + +**Entry point:** `js/main.js` - configures RequireJS, initializes theme, loads main app module + +**Module loading:** +- Main app module (`app/rspamd`) loads on page load +- Tab-specific modules lazy-load when tabs are activated + +## Key Components + +### Authentication & Connection +`js/app/rspamd.js` - `ui.connect()` + +Handles password authentication, stores credentials in `sessionStorage`, detects read-only mode + +### Tab Management & Navigation +`js/app/rspamd.js` - `tabClick()` + +Manages tab switching, lazy-loads tab-specific modules, handles auto-refresh + +### Auto-Refresh System +`js/app/rspamd.js` - `setAutoRefresh()` + +Periodically refreshes tab data, pauses when page hidden (via Visibility.js), shows countdown timer + +### API Communication +`js/app/common.js` - `ui.query(url, options)` + +Sends HTTP requests to Controller API, supports multi-server queries, handles authentication and errors + +### Theme System +`js/main.js` - Theme initialization and `window.rspamd.theme` API + +Manages light/dark/auto theme switching, persists preferences, responds to system theme changes + +### Statistics Display +`js/app/stats.js` + +Fetches and displays server statistics (Status tab): version, uptime, message counts, action distribution + +### Throughput Graphs +`js/app/graph.js` + +Renders time-series graphs and pie charts (Throughput tab) using D3Evolution and D3Pie + +### Message History +`js/app/history.js` (data fetching), `js/app/libft.js` (table rendering) + +Displays processed message history (History tab), handles FooTable initialization, row expansion, symbol details + +### Configuration Management +`js/app/config.js` + +Manages actions and maps (Configuration tab): load, edit, save settings + +### Symbol Management +`js/app/symbols.js` + +Displays and edits symbol scores (Symbols tab) + +### Message Scanning & Learning +`js/app/upload.js` + +Handles message upload, scanning, Bayes classifier training, fuzzy hash management (Scan tab) + +### Selector Testing +`js/app/selectors.js` + +Tests Rspamd selectors against messages (Selectors tab) + +### Table Utilities +`js/app/libft.js` + +Shared utilities for FooTable: data preprocessing, table initialization, pagination, sorting + +### FooTable Icons +`js/app/footable-fontawesome.js` + +Integrates Font Awesome icons with FooTable + +## Data Flow + +**Typical interaction pattern:** +1. User action (click, input) → Event handler +2. Data preparation +3. `common.query()` → API request(s) to server(s) +4. Response processing +5. UI update (DOM, tables, charts) + +## Common Patterns + +### Event Handlers +Use function expressions `function() {}` when you need `this` context (event target element), otherwise use arrow functions `() => {}`. + +### API Calls +Most API communication goes through `common.query(endpoint, options)` which handles multi-server requests, authentication, progress tracking, and error handling. + +### Table Management +Tables use FooTable library. Two main patterns: +- **Initial load**: destroy old table → process data → initialize FooTable → bind event handlers +- **Update data**: use FooTable API to update existing table without re-initialization + +### Module Structure +Each tab module returns a `ui` object with public methods (e.g., `ui.getSymbols()`, `ui.draw()`). These methods are called when tabs are activated. + +## State Management + +**Persistent storage (localStorage):** +- Theme preference +- Locale settings +- AJAX timeout +- Page size preferences + +**Session storage (sessionStorage):** +- Authentication password +- Server credentials and capabilities +- Error suppression flags + +**Global state:** +- `common.neighbours[]` - Configured servers +- `common.tables{}` - FooTable instances +- `timer_id[]` - Active refresh timers +- `checked_server` - Currently selected server + +## Technical Requirements + +**Browser capabilities needed:** +- Modern JavaScript (ES6+: arrow functions, const/let, template literals) +- Page Visibility API +- CSS Custom Properties + +**Network:** +- Browser must have network access to all configured controllers +- WebUI makes API requests from the browser to each controller independently (the controller serving the WebUI does not act as an intermediary) diff --git a/interface/README.md b/interface/README.md index a56aa66b93..350b119772 100644 --- a/interface/README.md +++ b/interface/README.md @@ -45,6 +45,13 @@ Password option should be changed for sure for your specific configuration. Encr Interface itself is written in pure HTML5/js and, hence, it requires zero setup. Just enter a password for webui access and you are ready. +## Development + +For developers looking to contribute to or modify the WebUI, see [ARCHITECTURE.md](ARCHITECTURE.md) for: +- Code structure and organization +- Technology stack details +- Development patterns and practices + ## Contact information Rspamd interface is distributed under the terms of [MIT license](http://opensource.org/licenses/MIT). For all questions related to this -- 2.47.3