# Admin Panel Architecture

The AjaxPress admin panel is a Single Page Application built with Solid.js, served inside the WordPress admin. It provides a modern, reactive interface for all plugin configuration.

## Technology Stack

| Layer | Technology |
|-------|-----------|
| Framework | Solid.js 1.9.3 |
| Router | @solidjs/router 0.15.2 |
| Build | Vite with vite-plugin-solid |
| Styling | Tailwind CSS 3.0.23 |
| Code Editor | WordPress CodeMirror (wp.codeEditor) |

## Entry Point

**File:** `src/admin/index.jsx`

The app mounts into `#ajaxpress-app` (rendered by PHP `Admin\Hooks::render_settings_page()`). Uses `HashRouter` for client-side routing to avoid conflicts with WordPress admin URL structure.

A capture-phase click listener on the app container prevents Solid.js router from intercepting external links.

## Routing

**File:** `src/admin/utility/routes.jsx`

| Path | Component | Description |
|------|-----------|-------------|
| `/` | Basic | SPA toggle, prefetch, admin settings |
| `/advanced` | Advanced | Exclusions, custom CSS, import/export |
| `/animations` | Animations | Loader type, transitions, duration |
| `/cache` | Cache | Cloudflare edge caching |
| `/license` | License | Key management, plans |
| `/help` `/help/:tab` | Help | Documentation tabs |
| `*` | NotFound | 404 fallback |

## State Management

State is managed through Solid.js context providers, combined into a single `AppProvider` wrapper.

### SettingsContext

**Store file:** `src/admin/utility/stores/settings.js`

Manages the plugin settings lifecycle:

- Initializes from `window.ajaxpress_admin_vars.settings`
- Tracks dirty state by comparing current values against last-saved snapshot
- Provides `saveSettings()`, `exportSettings()`, `importSettings()`, `resetSettings()`, `discardChanges()`
- Save sends POST to `/wp-json/ajaxpress/settings`

### AutosaveContext

**Store file:** `src/admin/utility/stores/autosave.js`

Debounced auto-save with status tracking:

- 2-second debounce on settings changes
- Status cycle: `idle` -> `saving` -> `saved` (2s) -> `idle`
- Error state shows for 5 seconds before returning to idle
- `saveNow()` bypasses debounce for immediate save

### LicenseContext

**Store file:** `src/admin/utility/stores/license.js`

License state and operations:

- Reads initial state from `window.ajaxpress_admin_vars`
- `isLocked` computed signal: `true` if no active license
- `maskedKey`: Shows first 7 and last 7 characters
- `activate()` / `deactivate()` manage license lifecycle
- `refreshLicense()` checks every 1 hour (localStorage cache)
- `fetchPlans()` retrieves pricing (12-hour cache)

### ModalContext

**Store file:** `src/admin/utility/stores/modal.js`

Confirmation modals and toast notifications:

- `fire(options)` returns a `Promise<boolean>` (ok/cancel)
- Options: `title`, `content`, `ok`, `cancel`, `okVariant`, `size`
- `toast(text, type, timer)` for success/error/info messages

### TourContext

**Store file:** `src/admin/utility/stores/tour.js`

Onboarding tour system:

- Two modes: `QUICK` and `FULL`
- Auto-starts if not completed or dismissed
- Steps filtered per license status (removes pricing for pro users)
- Auto-navigates to correct page per step
- Keyboard support: Arrow keys, Enter, Escape
- Persists state to backend via REST API

## Layout Component

**File:** `src/admin/views/Layout.jsx`

The root layout wrapping all routes:

- Sidebar navigation with collapsible state
- Mobile responsive menu
- Unsaved changes modal (prevents navigation without saving)
- Diagnostic permission notice
- Promotional countdown timer
- Tour overlay integration

## View Components

### Basic (`src/admin/views/Basic.jsx`)

Essential SPA settings:
- Enable SPA navigation toggle
- Enable admin SPA toggle (with Beta badge)
- Prefetch toggle (shown when SPA enabled)
- Disable for admins toggle
- Block keyboard reload toggle
- Speed meter visualization

### Advanced (`src/admin/views/Advanced.jsx`)

Power user settings:
- Persistent element selectors (textarea)
- Link exclusion patterns (textarea)
- Custom CSS editor (CodeMirror)
- Tools: export, import (with validation), reset (double confirmation)

### Animations (`src/admin/views/Animations.jsx`)

Visual configuration:
- Loader type: Progress Bar / Spinner / None
- Animation type: Fade / Slide / Flip / Scale
- Duration: Fast (0.2s) / Normal (0.3s) / Slow (0.5s)
- Live preview with mobile toggle

### Cache (`src/admin/views/Cache.jsx`)

Cloudflare integration UI with three sub-components:
- **CloudflareSetup** -- API token input and verification
- **CloudflareSection** -- Zone selection and deployment
- **CloudflareStatus** -- Connection status, purge controls, auto-purge toggle

### License (`src/admin/views/License.jsx`)

License management:
- Key input with masked display
- Activate/deactivate buttons
- License details (plan, expiration, activations)
- Pricing plans with tier switcher (Personal/Agency)
- URL parameter auto-activation (`?license_key=XXX`)

### Help (`src/admin/views/Help.jsx`)

Documentation with tabs:
- Getting Started, Tutorials, Dev Reference, Troubleshooting, Changelog, Feedback
- Global search modal with keyboard navigation
- Search result highlighting

## Reusable Components

Located in `src/admin/components/`:

| Component | Purpose |
|-----------|---------|
| `Switch` | Toggle with lock state and pro badge |
| `Button` | Multi-variant button (primary/secondary/danger/ghost) |
| `Text` | Text input |
| `Textarea` | Multi-line input |
| `Select` | Dropdown select |
| `Slider` | Range input |
| `ColorPicker` | Color selection |
| `CodeEditor` | Syntax-highlighted editor (CodeMirror wrapper) |
| `SegmentedControl` | Button group selector |
| `Tooltip` | Info popup (floating on desktop, drawer on mobile) |
| `Spin` | Loading spinner |
| `NewTag` | "New" badge |
| `Tour` | Onboarding overlay with spotlight and tooltip |

## API Layer

**File:** `src/admin/utility/api.js`

Singleton API client:

- `get(url)` and `post(url, data)` methods
- Sends `X-WP-Nonce` header from `window.ajaxpress_admin_vars.rest.nonce`
- Base URL from `window.ajaxpress_admin_vars.rest.url`
- JSON request/response format