csemazharul/wp-plugin-starter

1. What this repo is

This is a WordPress plugin starter kit. The root package is a plugin distribution that combines a PHP backend, a React/Vite frontend, database migrations, and a custom CLI (wp-kit) for initialization and code generation.

2. Top-level boundary

The main runtime boundary is WordPress itself. The plugin is loaded by WordPress via the plugin entry file at the repo root, then bootstraps code from backend/bootstrap.php into the backend/app namespace. The frontend is built separately and embedded/served inside the WordPress plugin context.

3. Backend bootstrap and plugin lifecycle

backend/bootstrap.php is the backend entry point. It wires autoloading and plugin startup through backend/app/Plugin.php, with configuration coming from backend/app/Config.php and environment values loaded by backend/app/Dotenv.php. This is the central PHP initialization path for activation-time and request-time behavior.

4. Plugin structure and providers

The backend follows a provider-style structure:

- backend/app/Providers/HookProvider.php registers WordPress hooks and routes.

- backend/app/Providers/InstallerProvider.php handles install/activate/uninstall behavior, especially migrations.

This keeps lifecycle concerns separate from request handling and schema setup.

5. HTTP routing layer

Request handling is split across backend/hooks/api.php and backend/hooks/ajax.php. These files define REST and AJAX routes using the WPKit router. This is the main application boundary for server-side interactions exposed to the frontend or WordPress admin.

6. Middleware and request protection

Middleware lives under backend/app/HTTP/Middleware/, including NonceCheckerMiddleware.php and AdminCheckerMiddleware.php. These are used to protect routes with nonce validation and admin authorization, so the architecture has explicit security gates around privileged requests.

7. Admin UI and view composition

The plugin includes a server-side view layer under backend/app/Views/ with layout pieces like Layout.php, Head.php, Body.php, and HtmlTagModifier.php. backend/app/src/Menu.php defines the WordPress admin menu entry. This suggests a plugin page that is mounted into the WP admin shell and rendered through a mix of PHP templates and frontend app mounting.

8. Database schema management

Schema changes are versioned in backend/db/Migrations/. InstallerProvider registers migrations for activation and uninstall rollback. The README shows these migrations use WPKit’s migration helper and WP table prefixing, so persistence is managed as first-class plugin infrastructure rather than ad hoc SQL.

9. Frontend application

The frontend lives under frontend/src/ and is a separate React app with TypeScript. frontend/src/main.tsx is the entry point, Welcome.tsx is the default screen, and frontend/src/config/config.ts binds runtime values from the server. Styling is in frontend/src/resource/styles/, and the stack includes Vite, Tailwind CSS, and Ant Design.

10. Backend-to-frontend data flow

The frontend communicates back to WordPress through request helpers in frontend/src/common/helpers/request.ts, which are intended to hit the plugin’s REST/AJAX endpoints. In development, frontend/src/config/devHotModule.js and .env settings point the frontend at a Vite dev server, so the UI can be served with HMR while still running inside WordPress.

11. CLI initializer and code generation

The wp-kit CLI is a major architectural component, not just tooling. php wp-kit plugin:init replaces placeholders, updates backend config, creates the plugin file, and installs dependencies with namespace isolation. Generators create controllers, models, and migrations in the correct backend folders, which means project structure is intentionally scaffold-driven.

12. Dependency and namespace isolation

composer.json and the README indicate PHP dependencies are isolated via Imposter namespace transformation. This matters because the plugin can ship its own vendor code without colliding with WordPress or other plugins. That isolation is part of the deployment boundary.

13. Development environment

The repo supports two dev modes: local WordPress and Docker-based wp-env via .wp-env.json. The documented pnpm env:start path spins up WordPress, auto-activates the plugin, and exposes WordPress admin plus phpMyAdmin. Vite runs separately for frontend hot reload.

14. Quality, tests, and CI

The repo has layered quality gates: ESLint/Prettier/Stylelint for frontend, PHPStan/PHPCS/Rector for backend, Vitest for frontend tests, PHPUnit for PHP tests, and Playwright for browser automation. GitHub Actions CI (.github/workflows/ci.yml) likely runs these checks together, so the architecture includes both runtime code and strong verification tooling.