# 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)