superpowers
1 day ago
addons.md
1 week ago
src-improvements.md
1 day ago
tech-stack.md
1 day ago
vulberability.md
1 week ago
tech-stack.md
122 lines
| 1 | # Advanced Ads — Tech Stack |
| 2 | |
| 3 | **Plugin:** Advanced Ads v2.0.20 |
| 4 | **Requires:** WordPress ≥ 5.7, PHP ≥ 7.4 |
| 5 | **License:** GPL-2.0+ |
| 6 | **Knowledge graph:** Understand Anything (978 files, last analyzed 2026-06-15) |
| 7 | |
| 8 | --- |
| 9 | |
| 10 | ## Backend — PHP |
| 11 | |
| 12 | | Concern | Detail | |
| 13 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | |
| 14 | | Language | PHP ≥ 7.4 | |
| 15 | | Autoloading | PSR-4 (`Advanced_Ads\` → `src/`) + classmap for legacy (`includes/`, `admin/`, `classes/`, `public/`, selected modules) | |
| 16 | | Dependency manager | Composer | |
| 17 | | Framework | `advanced-ads/framework` (internal, dev-main) | |
| 18 | | Mobile detection | `mobiledetect/mobiledetectlib` 3.74.3 | |
| 19 | | Background jobs | `woocommerce/action-scheduler` ^3.9 | |
| 20 | |
| 21 | ### PHP Dev Dependencies |
| 22 | |
| 23 | | Package | Version | Purpose | |
| 24 | | -------------------------------------- | ------- | ------------------ | |
| 25 | | `phpunit/phpunit` | ^9.6 | Unit testing | |
| 26 | | `wp-coding-standards/wpcs` | ^3.0.0 | Code style (PHPCS) | |
| 27 | | `phpcompatibility/phpcompatibility-wp` | ^2.1 | PHP compat checks | |
| 28 | | `symfony/css-selector` | ^5.4 | Test utilities | |
| 29 | | `yoast/phpunit-polyfills` | ^4.0 | PHPUnit polyfills | |
| 30 | |
| 31 | ### PHP Architecture Layers |
| 32 | |
| 33 | ``` |
| 34 | src/ PSR-4 namespaced (Advanced_Ads\) — new code |
| 35 | includes/ Classmap legacy — core plugin classes |
| 36 | admin/ Classmap legacy — admin classes |
| 37 | classes/ Classmap legacy — shared helpers |
| 38 | public/ Classmap legacy — frontend |
| 39 | modules/ Feature modules (ad-blocker, ad-positioning, adblock-finder, |
| 40 | ads-txt, gadsense, gutenberg, one-click, pef, privacy) |
| 41 | upgrades/ Versioned DB migration scripts |
| 42 | ``` |
| 43 | |
| 44 | --- |
| 45 | |
| 46 | ## Frontend — JavaScript / React |
| 47 | |
| 48 | | Concern | Detail | |
| 49 | | ---------------- | ---------------------------------------------------------------- | |
| 50 | | Runtime | Node.js ≥ 20.0.0, npm ≥ 9.0.0 | |
| 51 | | UI framework | React (via `@wordpress/scripts`) | |
| 52 | | Language | JavaScript + TypeScript | |
| 53 | | Build tool | Webpack (extended from `@wordpress/scripts` default config) | |
| 54 | | CSS framework | Tailwind CSS v4 (`@tailwindcss/postcss` ^4.1.14) | |
| 55 | | CSS processing | PostCSS | |
| 56 | | State management | `@wordpress/data` (Redux-like store) | |
| 57 | | API layer | `@wordpress/api-fetch` (REST) | |
| 58 | | Icons | `lucide-react` ^1.3.0 | |
| 59 | | Class utilities | `clsx` ^2.1.1 + `tailwind-merge` ^3.5.0 | |
| 60 | | Legacy widgets | `select2` ^4.1.0-rc.0 | |
| 61 | | Routing | Custom SPA router via `useSyncExternalStore` (URL search params) | |
| 62 | | SVG handling | `@svgr/webpack` ^8.1.0 | |
| 63 | |
| 64 | ### Admin Screens (React SPAs) |
| 65 | |
| 66 | | Screen | Entry | |
| 67 | | ---------- | ------------------------------ | |
| 68 | | Ads | `src/admin/screen-ads/` | |
| 69 | | Ad Groups | `src/admin/screen-groups/` | |
| 70 | | Placements | `src/admin/screen-placements/` | |
| 71 | | Licenses | `src/admin/screen-licenses/` | |
| 72 | | Settings | `src/admin/screen-settings/` | |
| 73 | | Support | `src/admin/screen-support/` | |
| 74 | | Dashboard | `src/admin/screen-dashboard/` | |
| 75 | |
| 76 | All screens share a client-side router (`src/admin/router.js`) and central route registry (`src/admin/routes.js`). |
| 77 | |
| 78 | --- |
| 79 | |
| 80 | ## Testing |
| 81 | |
| 82 | | Layer | Tool | Command | |
| 83 | | -------- | ----------------------- | ------------------------- | |
| 84 | | PHP unit | PHPUnit ^9.6 | `composer test` | |
| 85 | | JS unit | wp-scripts test-unit-js | `npm run test:unit` | |
| 86 | | E2E | Playwright | `npm run test:playwright` | |
| 87 | |
| 88 | --- |
| 89 | |
| 90 | ## Code Quality |
| 91 | |
| 92 | | Tool | Scope | How invoked | |
| 93 | | ---------------------- | ---------- | ----------------------------------- | |
| 94 | | ESLint | JavaScript | `npm run lint:js` | |
| 95 | | Stylelint | CSS/SCSS | `npm run lint:css` | |
| 96 | | PHP_CodeSniffer (WPCS) | PHP | `npm run lint:php` / `bin/phpcs.sh` | |
| 97 | | PHPMD | PHP | `phpmd.xml` config present | |
| 98 | | husky + lint-staged | Pre-commit | Runs format + lint on staged files | |
| 99 | |
| 100 | --- |
| 101 | |
| 102 | ## CI/CD — GitHub Actions |
| 103 | |
| 104 | | Workflow | Purpose | |
| 105 | | ----------------------- | --------------------------------- | |
| 106 | | `php-unit.yml` | PHP unit test suite | |
| 107 | | `php-compatibility.yml` | Cross-version PHP compat checks | |
| 108 | | `playwright.yml` | End-to-end browser tests | |
| 109 | | `release.yml` | Plugin release packaging | |
| 110 | | `wordpress-deploy.yml` | Deploy to WordPress.org / hosting | |
| 111 | |
| 112 | --- |
| 113 | |
| 114 | ## Tooling |
| 115 | |
| 116 | | Tool | Purpose | |
| 117 | | ------------------- | ------------------------------------------------------------ | |
| 118 | | Understand Anything | Codebase knowledge graph (`.understand-anything/`) | |
| 119 | | WP-CLI | DB/install helpers (`composer global require wp-cli/wp-cli`) | |
| 120 | | WP-CLI i18n | Translation file generation | |
| 121 | | wp-advads (custom) | Internal build wrapper (`npx wp-advads build`) | |
| 122 |