# Architecture Overview

AjaxPress is a WordPress plugin that converts standard WordPress sites into Single Page Applications. It intercepts link clicks and form submissions, loads content via background iframes, and swaps visible content with animations -- all without full page reloads.

## System Components

```
+------------------------------------------------------------------+
|                        WordPress Site                             |
|                                                                   |
|  +------------------+    +-------------------+    +------------+  |
|  |   PHP Backend    |    |  Frontend Engine  |    | Admin SPA  |  |
|  |                  |    |  (Vanilla JS)     |    | (Solid.js) |  |
|  |  - Boot          |    |                   |    |            |  |
|  |  - Options       |    |  - IframeContainer|    | - Settings |  |
|  |  - Enqueues      |    |  - Transitions    |    | - License  |  |
|  |  - Templates     |    |  - Prefetch       |    | - Cache    |  |
|  |  - REST API      |    |  - Persistence    |    | - Help     |  |
|  |  - Cloudflare    |    |  - License Check  |    | - Tour     |  |
|  +--------+---------+    +--------+----------+    +------+-----+  |
|           |                       |                      |        |
|           v                       v                      v        |
|  +------------------+    +-------------------+    +------------+  |
|  | WordPress Core   |    |  Browser APIs     |    | WP REST    |  |
|  | - Options API    |    |  - postMessage    |    | API        |  |
|  | - Hooks API      |    |  - History API    |    |            |  |
|  | - User Meta API  |    |  - Web Animation  |    |            |  |
|  +------------------+    +-------------------+    +------------+  |
|                                                                   |
|  +-------------------------------------------------------------+ |
|  |                  Cloudflare (Optional)                       | |
|  |  - Worker Script (edge caching)                              | |
|  |  - Route Management                                          | |
|  |  - Cache Purge API                                           | |
|  +-------------------------------------------------------------+ |
+------------------------------------------------------------------+
```

## Component Responsibilities

### PHP Backend

The server-side layer handles plugin initialization, settings storage, asset enqueuing, and Cloudflare API integration. It follows a singleton pattern with a central boot loader that conditionally includes classes based on context (admin vs. frontend).

Key subsystems:
- **Boot** -- Plugin initialization, constant definitions, file inclusion
- **Options** -- Settings CRUD, default values, premium feature gating, migrations
- **Enqueues** -- Script/style registration with bot detection
- **Templates** -- Progress bar and spinner markup injection
- **REST API** -- Settings, license, tour, and Cloudflare endpoints
- **Cloudflare** -- API client, cache manager, auto-purge hooks

### Frontend SPA Engine

A vanilla JavaScript module (~14KB compiled) that runs on the public-facing site. It creates an iframe-based navigation system where page content loads in background iframes and is swapped into view with CSS animations.

Key subsystems:
- **IframeContainer** -- Parent/child iframe management and navigation
- **Transitions** -- Web Animation API-based page transitions
- **Prefetch** -- Background pre-loading on hover or mousedown
- **Persistence** -- Elements that survive navigation (audio/video players)
- **License** -- Periodic license validation with localStorage caching

### Admin SPA

A Solid.js application served within the WordPress admin. It provides a modern UI for configuring all plugin settings, managing licenses, setting up Cloudflare caching, and accessing documentation.

Key subsystems:
- **Context Providers** -- Settings, License, Autosave, Modal, Tour
- **Views** -- Basic, Advanced, Animations, Cache, License, Help
- **Components** -- Reusable form controls and UI elements

### Cloudflare Integration

An optional subsystem that deploys a Cloudflare Worker for edge caching. It manages the full lifecycle: token verification, worker upload, route creation, cache purging, and teardown. Auto-purge hooks respond to WordPress content changes.

## Request Lifecycle

### Standard Page Load (First Visit)

1. WordPress processes the request normally
2. `Boot::start()` initializes the plugin
3. `Enqueues` registers frontend JS/CSS (skips bots)
4. `Templates` injects loader markup in footer
5. Browser loads `ajaxpress.min.js`
6. Frontend creates iframe structure and wraps page content

### Subsequent Navigation (SPA Mode)

1. User hovers a link -- prefetch fires (if enabled)
2. Child iframe sends `AJAXPRESS_PREFETCH_REQUEST` to parent
3. Parent loads URL in hidden background iframe
4. User clicks the link
5. Child iframe sends `AJAXPRESS_NAVIGATE` to parent
6. Parent triggers transition animation (crossfade)
7. Background iframe becomes visible, old iframe hides
8. `history.pushState()` updates the browser URL
9. Persistent elements are preserved across the swap

### Admin Settings Save

1. User changes a setting in the Solid.js admin UI
2. Setting store updates (reactive signal)
3. Autosave context triggers after 2-second debounce
4. POST request to `/wp-json/ajaxpress/settings`
5. PHP REST handler updates WordPress options

## Security Model

- All REST endpoints require `manage_options` capability
- Requests authenticated via WordPress nonce (`X-WP-Nonce` header)
- Cloudflare API token encrypted with AES-256-CBC using `wp_salt('auth')`
- Frontend license validation uses base64-encoded endpoint
- No sensitive data exposed in client-side JavaScript