# PHP Backend Architecture

## Boot Process

The plugin initializes through a three-step process defined in `ajaxpress.php` and `includes/class-boot.php`.

### Entry Point (`ajaxpress.php`)

Defines two constants and triggers the boot sequence:

```php
define('AJAXPRESS', __FILE__);
define('AJAXPRESS_VERSION', '2.3.0');
require_once __DIR__ . '/includes/class-boot.php';
```

Also registers the activation hook (`ajaxpress_plugin_activation`) which:
- Resets diagnostic permission
- Clears tour state for all users
- Resets premium settings if license is inactive

### Boot Loader (`AjaxPress\Boot`)

`Boot::start()` runs immediately on file inclusion:

1. **Constants** -- Defines `AJAXPRESS_URL`, `AJAXPRESS_PATH`, `AJAXPRESS_INCLUDES`, `AJAXPRESS_PREFIX` (`ajaxpress_`)
2. **Common includes** -- Loads `Base`, `Options`, and all Cloudflare classes (always)
3. **Conditional includes**:
   - **Frontend** (non-admin): `Enqueues`, `Templates`
   - **Admin**: `Admin\Hooks`, `Admin\Enqueues`, `Admin\REST`, `Admin\Deactivate_Feedback`

## Class Hierarchy

```
AjaxPress\Base (abstract, singleton)
├── AjaxPress\Options
├── AjaxPress\Enqueues
├── AjaxPress\Templates
├── AjaxPress\Admin\Hooks
├── AjaxPress\Admin\Enqueues
├── AjaxPress\Admin\REST
├── AjaxPress\Admin\Deactivate_Feedback
└── AjaxPress\Cloudflare\Hooks
```

Non-extending classes:
- `AjaxPress\Boot` -- standalone initializer
- `AjaxPress\Cloudflare\API` -- Cloudflare API client
- `AjaxPress\Cloudflare\Cache` -- Cache operations manager

## Base Class (`AjaxPress\Base`)

Located at `includes/common/abstract-class-base.php`. Provides:

- **Singleton pattern** -- Each subclass maintains its own static instance via `get_instance()`
- **Hook registration** -- `start()` calls `actions()` and `filters()` (overridden by subclasses)
- **License check** -- `is_license_active()` reads `ajaxpress_license` option, applies `ajaxpress_is_license_active` filter

## Options Management (`AjaxPress\Options`)

Located at `includes/common/class-options.php`. Central settings manager.

### Settings Storage

All settings are stored as individual WordPress options prefixed with `ajaxpress_`. This allows granular updates without serializing/deserializing a single large option.

### Key Methods

| Method | Purpose |
|--------|---------|
| `get_default_settings()` | Returns all defaults, applies `ajaxpress_default_options` filter |
| `get_settings($filter_premium)` | Merges DB values with defaults, optionally strips premium features |
| `update_settings($new_settings)` | Iterates and updates each option individually |
| `get_premium_features()` | Returns array of 47 premium feature keys |
| `filter_premium_settings($settings)` | Resets premium features to defaults if license inactive |
| `reset_premium_settings()` | Writes default values for premium features to DB |

### Migrations

Tracked via `ajaxpress_migrated_version` option. Current migration:

**v2.3.0:**
- `disable_logged_in_users` renamed to `disable_for_admins`
- `loader_image_position` renamed to `loader_layout`
- Boolean `progressbar`/`loader` fields consolidated into `loader_type` enum (`progressbar|spinner|none`)
- Removed deprecated options cleaned from database

## Frontend Classes

### Enqueues (`AjaxPress\Enqueues`)

Located at `includes/classes/class-enqueues.php`. Hooks into `wp_enqueue_scripts`.

- Skips enqueuing for 17 known bot user agents
- Respects `disable_for_admins` setting
- Enqueues `ajaxpress.min.css` and `ajaxpress.min.js`
- Localizes settings to `window.ajaxpress_vars` containing:
  - REST URL and nonce
  - Site info (name, language)
  - Plugin URL and version
  - Current settings
  - Navigation toggle (filterable via `ajaxpress_navigation`)
  - User login status, license data, debug mode
- Injects inline CSS for animation variables

### Templates (`AjaxPress\Templates`)

Located at `includes/classes/class-templates.php`. Hooks into `wp_footer`.

- Loads `templates/progressbar.php` or `templates/loader.php` based on `loader_type`
- Provides `is_ajax_request()` static method (checks `Ajaxpress-Ajax` header)
- Includes `hex2rgba()` color conversion helper

## Admin Classes

### Hooks (`AjaxPress\Admin\Hooks`)

Located at `includes/admin/class-admin-hooks.php`.

- Registers settings page under Settings menu via `add_options_page()`
- Renders `<div id="ajaxpress-app"></div>` container for Solid.js app
- Adds "Settings" and "Activate License" plugin action links

### Enqueues (`AjaxPress\Admin\Enqueues`)

Located at `includes/admin/class-admin-enqueues.php`.

- Loads `admin.min.js` and `admin.min.css` on AjaxPress admin pages
- Optionally enqueues frontend SPA script in admin (if `enable_admin_spa` enabled)
- Localizes `window.ajaxpress_admin_vars` with:
  - Server info (PHP version, MySQL version, platform)
  - Site info (active plugins, theme, multisite status)
  - Default and current settings
  - Cloudflare connection status
  - Diagnostic permission

### REST API (`AjaxPress\Admin\REST`)

Located at `includes/admin/class-admin-rest.php`. See [REST Endpoints](../api/rest-endpoints.md) for full reference.

### Deactivate Feedback (`AjaxPress\Admin\Deactivate_Feedback`)

Located at `includes/admin/class-deactivate-feedback.php`.

- Enqueues `deactivate.min.js` only on `plugins.php`
- Collects site and server metadata for feedback context