| 1 |
# Architecture Overview |
| 2 |
|
| 3 |
CartFlows is a WordPress plugin that creates checkout pages and sales funnels for WooCommerce. It follows a modular, singleton-bootstrapped architecture with a modern React frontend. |
| 4 |
|
| 5 |
## Plugin Bootstrap |
| 6 |
|
| 7 |
``` |
| 8 |
cartflows.php |
| 9 |
└── classes/class-cartflows-loader.php (Cartflows_Loader singleton) |
| 10 |
├── admin-loader.php (admin-only components) |
| 11 |
├── modules/ (feature modules) |
| 12 |
└── compatibilities/ (third-party integrations) |
| 13 |
``` |
| 14 |
|
| 15 |
The plugin entry point (`cartflows.php`) sets the `CARTFLOWS_FILE` constant and immediately requires the loader. `Cartflows_Loader` is a **singleton** — a single class instance bootstraps every plugin component, ensuring no duplicate initialisation. |
| 16 |
|
| 17 |
Admin functionality is gated behind `is_admin()` and loaded via `admin-loader.php`, which boots the React-powered admin interface. |
| 18 |
|
| 19 |
## High-Level Component Map |
| 20 |
|
| 21 |
``` |
| 22 |
┌─────────────────────────────────────────────────────────────┐ |
| 23 |
│ cartflows.php │ |
| 24 |
└──────────────────────┬──────────────────────────────────────┘ |
| 25 |
│ |
| 26 |
┌────────────▼────────────┐ |
| 27 |
│ Cartflows_Loader │ (singleton, classes/) |
| 28 |
│ register_activation_ │ |
| 29 |
│ hook, init hooks │ |
| 30 |
└──┬────────────┬─────────┘ |
| 31 |
│ │ |
| 32 |
┌─────────▼──┐ ┌────▼──────────────────────────────┐ |
| 33 |
│ Frontend │ │ Admin (admin-loader.php) │ |
| 34 |
│ classes/ │ │ ┌─────────────────────────────┐ │ |
| 35 |
│ class- │ │ │ REST API (admin-core/api/) │ │ |
| 36 |
│ cartflows-│ │ │ AJAX (admin-core/ajax/) │ │ |
| 37 |
│ frontend │ │ │ Menus (admin-core/inc/) │ │ |
| 38 |
└─────────┬──┘ │ │ React Apps (assets/build/) │ │ |
| 39 |
│ │ └─────────────────────────────┘ │ |
| 40 |
│ └───────────────────────────────────┘ |
| 41 |
│ |
| 42 |
┌─────────▼──────────────────────────────────────────┐ |
| 43 |
│ Feature Modules (modules/) │ |
| 44 |
│ flow · checkout · optin · landing · thankyou │ |
| 45 |
│ gutenberg · elementor · beaver-builder · bricks │ |
| 46 |
│ email-report · woo-dynamic-flow │ |
| 47 |
└────────────────────────────────────────────────────┘ |
| 48 |
``` |
| 49 |
|
| 50 |
## Key Directories |
| 51 |
|
| 52 |
| Path | Purpose | |
| 53 |
|------|---------| |
| 54 |
| `cartflows.php` | Plugin entry point; sets `CARTFLOWS_FILE` constant | |
| 55 |
| `classes/` | Core PHP classes — loader, admin, frontend, helper, utils | |
| 56 |
| `classes/importer/` | Template importer for Elementor, Gutenberg, Divi, BB | |
| 57 |
| `classes/logger/` | Logging system (WC logger integration) | |
| 58 |
| `admin-core/` | All admin-facing PHP + React assets | |
| 59 |
| `admin-core/api/` | REST API endpoint classes extending `ApiBase` | |
| 60 |
| `admin-core/ajax/` | AJAX handler classes extending `AjaxBase` | |
| 61 |
| `admin-core/inc/` | Admin menus, global settings, WP-CLI commands | |
| 62 |
| `admin-core/assets/src/` | React source (editor-app + settings-app) | |
| 63 |
| `admin-core/assets/build/` | Compiled JS/CSS (committed to repo) | |
| 64 |
| `modules/` | Feature modules loaded conditionally | |
| 65 |
| `compatibilities/` | Third-party theme/plugin integrations | |
| 66 |
| `woocommerce/` | WooCommerce template overrides | |
| 67 |
| `wizard/` | Setup wizard (separate webpack build) | |
| 68 |
| `libraries/` | Vendored BSF packages (analytics, notices, nps-survey) | |
| 69 |
| `tests/php/` | PHPUnit test cases | |
| 70 |
| `tests/e2e/` | Playwright E2E tests | |
| 71 |
|
| 72 |
## PHP Namespaces |
| 73 |
|
| 74 |
| Namespace | Location | Purpose | |
| 75 |
|-----------|----------|---------| |
| 76 |
| `CartflowsAdmin\AdminCore\Api` | `admin-core/api/` | REST API controllers | |
| 77 |
| `CartflowsAdmin\AdminCore\Ajax` | `admin-core/ajax/` | AJAX handlers | |
| 78 |
|
| 79 |
Core classes in `classes/` use unprefixed globals following WordPress conventions. |
| 80 |
|
| 81 |
## Admin Interface Architecture |
| 82 |
|
| 83 |
Two independent React apps are compiled separately: |
| 84 |
|
| 85 |
| App | Entry Point | Build Output | Purpose | |
| 86 |
|-----|-------------|-------------|---------| |
| 87 |
| **editor-app** | `EditorApp.js` | `editor-app.js` | Flow/step editor (canvas, node types, step settings) | |
| 88 |
| **settings-app** | `SettingsApp.js` | `settings-app.js` | Dashboard, analytics, global settings, flows list | |
| 89 |
|
| 90 |
Both apps use: |
| 91 |
- **React 18** with `createRoot` |
| 92 |
- **Redux** for global state |
| 93 |
- **React Router** (v5) for in-app navigation |
| 94 |
- **`@wordpress/api-fetch`** for REST API calls |
| 95 |
- **Tailwind CSS** for styling |
| 96 |
|
| 97 |
## REST API |
| 98 |
|
| 99 |
All admin REST endpoints live under the `cartflows/v1` namespace. Every controller class extends the abstract `ApiBase` (which extends `WP_REST_Controller`). |
| 100 |
|
| 101 |
See [](REST-API-ReferenceREST-API-Reference](REST-API-Reference](REST-API-Reference) for the full endpoint list. |
| 102 |
|
| 103 |
## AJAX API |
| 104 |
|
| 105 |
AJAX handlers use the action prefix `cartflows_`. Every handler class extends the abstract `AjaxBase`, which registers `wp_ajax_cartflows_{action}` hooks and handles nonce verification automatically. |
| 106 |
|
| 107 |
See [](AJAX-API-ReferenceAJAX-API-Reference](AJAX-API-Reference](AJAX-API-Reference) for the full handler list. |
| 108 |
|
| 109 |
## Module System |
| 110 |
|
| 111 |
Each feature is a self-contained module under `modules/`. Modules register their own hooks, post meta, and templates. They are loaded by `Cartflows_Loader` on `plugins_loaded`. |
| 112 |
|
| 113 |
See [](Feature-ModulesFeature-Modules](Feature-Modules](Feature-Modules) for details on each module. |
| 114 |
|
| 115 |
## Data Flow |
| 116 |
|
| 117 |
``` |
| 118 |
Browser (React) ──► REST API (cartflows/v1) ──► PHP Controller |
| 119 |
│ |
| 120 |
WordPress DB |
| 121 |
(posts, postmeta, |
| 122 |
options table) |
| 123 |
|
| 124 |
Browser (React) ──► AJAX (wp_ajax_cartflows_*) ──► PHP Handler |
| 125 |
``` |
| 126 |
|
| 127 |
## Related Pages |
| 128 |
|
| 129 |
- [](WordPress-Plugin-StructureWordPress-Plugin-Structure](WordPress-Plugin-Structure](WordPress-Plugin-Structure) |
| 130 |
- [](Frontend-ArchitectureFrontend-Architecture](Frontend-Architecture](Frontend-Architecture) |
| 131 |
- [](REST-API-ReferenceREST-API-Reference](REST-API-Reference](REST-API-Reference) |
| 132 |
- [](AJAX-API-ReferenceAJAX-API-Reference](AJAX-API-Reference](AJAX-API-Reference) |
| 133 |
- [](Feature-ModulesFeature-Modules](Feature-Modules](Feature-Modules) |
| 134 |
- [](Build-SystemBuild-System](Build-System](Build-System) |
| 135 |
|
