# Architecture Overview

Convert Plus is a WordPress plugin built around a custom internal framework called **Smile Framework**. The plugin converts website visitors into leads using three display module types: Modal Popup, Slide-In Popup, and Info Bar.

## Class Hierarchy

```
Smile_Framework          (framework/class-smile-framework.php)
    └── Convert_Plug     (classes/class-convert-plug.php)
```

`Convert_Plug` extends `Smile_Framework` and is the plugin's main application class. It is instantiated once at plugin load time via `convertplug.php`.

## Load Order

```
convertplug.php
  ├── classes/class-convert-plug.php           ← main class (includes Smile_Framework)
  ├── lib/astra-notices/                        ← admin-only notice library
  ├── admin/bsf-analytics/                      ← usage analytics (BSF Analytics)
  ├── framework/class-cplus-ultimate-google-font-manager.php  ← admin only
  ├── classes/class-convert-plug-maxmind-geolocation.php      ← admin only
  └── classes/class-convert-plug-filesystem.php               ← admin only

On `init` (via Smile_Framework::load_framework_functions):
  ├── framework/classes/class-smile-framework-mapper.php
  ├── framework/classes/class.style-framework.php
  ├── framework/classes/class-cpimport.php
  ├── framework/functions/functions.php
  └── framework/lib/fields/**/*.php             ← input type field definitions

On admin access (via Convert_Plug::__construct):
  ├── admin/ajax-actions.php                    ← all wp_ajax_* handlers
  └── framework/class-add-convertplug-widget.php
```

## Module Loading

Modules are registered in `modules/config.php` and stored in the `convert_plug_modules` WordPress option. Only enabled modules are loaded:

| Module | Class | File |
|--------|-------|------|
| Modal Popup | `Smile_Modals` | `modules/modal/class-smile-modals.php` |
| Info Bar | `Smile_Info_Bars` | `modules/info_bar/class-smile-info-bars.php` |
| Slide In Popup | `Smile_Slide_Ins` | `modules/slide_in/class-smile-slide-ins.php` |

## Key Subsystems

| Subsystem | Location | Description |
|-----------|----------|-------------|
| Smile Framework | `framework/` | Options storage, module/addon registration, field rendering |
| AJAX Actions | `admin/ajax-actions.php` | All backend AJAX and form handlers |
| Contacts | `admin/contacts/` | Campaign and subscriber management |
| Analytics | `admin/ajax-actions.php` | Impression/conversion tracking per campaign |
| Geolocation | `classes/class-convert-plug-maxmind-geolocation.php` | MaxMind GeoLite2 country targeting |
| BSF Core | `admin/bsf-core/` | License management, auto-updates |
| BSF Analytics | `admin/bsf-analytics/` | Product usage analytics |

## WordPress Hooks Overview

The `Convert_Plug` constructor registers all core hooks:

- `wp_loaded` — sets capabilities and options
- `admin_menu` — registers the Convert Plus admin pages
- `wp_enqueue_scripts` — loads front-end JS/CSS for active campaigns
- `admin_enqueue_scripts` — loads admin assets
- `plugins_loaded` — loads text domain (`smile`)
- `the_content` — injects after-content trigger marker
- `wp_ajax_cp_display_preview_*` — modal/slide-in/info-bar live preview

## Data Storage

All plugin data is stored in WordPress options (no custom database tables for campaigns):

| Option | Contents |
|--------|----------|
| `convert_plug_settings` | Global plugin settings |
| `convert_plug_modules` | Array of active module slugs |
| `convert_plug_debug` | Debug mode flags |
| `smile_lists` | All campaigns (keyed by campaign ID) |
| `cp_previous_version` | Last installed version (used for upgrade routines) |
| `convertplus_maxmind_geolocation_settings` | MaxMind database prefix and license key |

Subscriber data is stored per-list inside the `smile_lists` option structure.

## Related Pages

- [Plugin Structure](Plugin-Structure)
- [Smile Framework](Smile-Framework)
- [Module System](Module-System)
- [Environment Configuration](Environment-Configuration)