# Happy Elementor Addons – Architecture Overview (Pro)

## 1️⃣ Core Directory Layout (shared with the free version)
| Folder | Purpose |
|--------|---------|
| **`assets/`** | CSS/JS, images, fonts, and third‑party vendor libraries used by the front‑end UI of widgets and the admin panel. |
| **`base/`** | Base widget class (`widget-base.php`) that all Elementor widgets extend. Provides common helper methods (enqueue scripts, render wrappers). |
| **`classes/`** | Service layer handling admin UI, AJAX/REST, asset management, caching, conditions, dashboard/updater, WPML support, **license management**, and premium‑only services. |
| **`controls/`** | Custom Elementor controls (e.g., image selector, mask image, lazy select). |
| **`extensions/`** | Advanced kits that add extra Elementor editor capabilities (particle effects, liquid glass, multi‑layer parallax, design manager, etc.). |
| **`inc/`** | Miscellaneous helper functions (`functions.php`, `functions-template.php`, `functions-extensions.php`). |
| **`traits/`** | Re‑usable code fragments mixed into widgets or classes (markup helpers for premium widgets, lazy‑query builder). |
| **`templates/`** | PHP view files for admin pages, wizards, library UI, and premium‑only screens (license activation, design manager). |
| **`vendor/`** | Composer‑managed external dependencies (Appsero analytics, licensing SDK). |
| **`widgets/`** | One directory per Elementor widget. The Pro version adds ~80 premium widgets (e.g., `advanced‑pricing‑table`, `edd‑cart`, `gallery‑slider`). |
| **`wpml/`** | WPML integration files that make widget strings translatable. |
| **Root files** | `happy-elementors-addons-pro.php` – bootstrap, registers core managers with Elementor. `README.md`, `package.json`, `gulpfile.mjs` – documentation and build tooling. |

## 2️⃣ High‑Level Flow (adds premium paths)
1. **Bootstrap** (`happy-elementors-addons-pro.php`)
   - Confirms Elementor is active **and** a valid license key is present.
   - Instantiates core managers (same as free) **plus** `Credentials_Manager` and `Dashboard_Manager` for license activation and premium UI.
   - Hooks into Elementor’s `init` action.
2. **Registration**
   - **Widgets**: Premium widgets register alongside free ones via the same manager.
   - **Controls & Extensions**: Extra premium controls/extensions are registered in the same hook flow.
   - **Display Conditions**: Advanced conditions are read from `extensions/conditions/` and injected into Elementor’s “Display Conditions” UI.
3. **Rendering**
   - Same rendering pipeline as the free version, but premium widgets may pull data from additional sources (e.g., Easy Digital Downloads, WooCommerce) using the `Traits` such as `lazy-query-builder.php`.
4. **Front‑End Assets**
   - `Assets_Manager` enqueues premium assets only when required (e.g., particle effect scripts). Caching works identically to the free version.
5. **Admin & AJAX**
   - **License UI** lives under `templates/admin/` and is served by `Classes\Dashboard_Manager`.
   - **Premium AJAX** endpoints (e.g., live preview of design presets) are handled by `Classes\Ajax_Handler` and `Classes\Api_Handler`.
6. **Internationalization (WPML)**
   - Same mechanism as the free version; additional premium strings are added to the WPML mapping files.
7. **Design Manager (Pro‑only)**
   - `extensions/designs-manager.php` lets users save, export, and apply design presets across widgets.

## 3️⃣ Component Interaction Diagram (including premium pieces)
```mermaid
graph TD
    A[Plugin Bootstrap] --> B[Core Managers]
    B --> C[Widgets Manager]
    B --> D[Extensions Manager]
    B --> E[Assets Manager]
    B --> F[Ajax / API Handlers]
    B --> G[Credentials Manager]
    C --> H[Individual Widget Classes]
    D --> I[Extension Files]
    H --> J[Traits / Helper Functions]
    H --> K[Controls via Controls Manager]
    H --> L[Render → Front‑end Assets]
    L --> M[Assets Cache]
    F --> N[License / Pro Services]
    subgraph WPML
        O[WPML Manager] --> H
    end
    subgraph ProFeatures
        P[Pro Widgets] -.-> H
        Q[Pro Extensions] -.-> I
        R[Design Manager] -.-> D
    end
```

## 4️⃣ Testing Hot‑Spots (focus areas for a comprehensive test suite)
| Layer | Typical Test Targets |
|-------|----------------------|
| **Bootstrap** | License validation flow (valid, expired, missing); manager instantiation when Elementor is present/absent. |
| **Widgets** | All free and premium widgets – control definitions, `render()` HTML snapshots, lazy‑query data retrieval. |
| **Controls** | New premium controls (image selector, mask image, lazy select) – registration and default values. |
| **Extensions** | Advanced extensions (particle effects, liquid glass, multi‑layer parallax, design manager) – hook registration and DOM/CSS impact. |
| **Assets Manager** | Conditional enqueueing of premium assets, cache key uniqueness. |
| **Ajax / REST** | License activation/deactivation endpoints, premium AJAX actions (design preset CRUD). |
| **License Management** | Simulated responses from the licensing server, error handling, UI state changes. |
| **WPML** | Correct mapping of premium strings for different locales. |
| **Design Manager** | Saving, retrieving, applying design presets; export/import workflow. |

## 5️⃣ Where to Add New Code (Pro‑specific)
- **New premium widget** → `widgets/<slug>/<widget>.php` (extend `Base\Widget_Base`).
- **New premium control** → `controls/<control>.php` (register via `Controls_Manager`).
- **New premium extension** → `extensions/<extension>.php` (add filters/actions, may involve front‑end assets).
- **License‑related code** → `classes/credentials-manager.php`, `classes/dashboard-manager.php`.
- **Design presets** → `extensions/designs-manager.php` and related template files.
- **Utility functions** → `inc/functions-*.php`.

---

*This file is intended to onboard developers instantly. It gives a complete, high‑level map of the Pro plugin’s architecture, the added premium pieces, and the most important testing surfaces. No follow‑up should be required to get started.*