# csemazharul/wp-plugin-starter architecture

> Architecture diagram of the GitHub repository csemazharul/wp-plugin-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/csemazharul/wp-plugin-starter
- Repository: https://github.com/csemazharul/wp-plugin-starter

## Overview

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.

Main entry points: [`backend/app/Providers/HookProvider.php`](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Providers/HookProvider.php) (Hooks), [`backend/app/Plugin.php`](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Plugin.php) (Plugin Core), [`frontend/src/main.tsx`](https://github.com/csemazharul/wp-plugin-starter/blob/main/frontend/src/main.tsx) (Frontend App), [`.github/workflows/ci.yml`](https://github.com/csemazharul/wp-plugin-starter/blob/main/.github/workflows/ci.yml) (CI Checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["WordPress Runtime"]
  node_plugin_root["Plugin Shell<br/>wordpress plugin"]
end

subgraph group_backend["Backend"]
  node_backend_bootstrap["Bootstrap<br/>php entry<br/>[bootstrap.php]"]
  node_plugin_core["Plugin Core<br/>app kernel<br/>[Plugin.php]"]
  node_config["Config<br/>settings<br/>[Config.php]"]
  node_dotenv["Dotenv<br/>env loader<br/>[Dotenv.php]"]
  node_hook_provider["Hooks<br/>provider<br/>[HookProvider.php]"]
  node_installer_provider["Installer<br/>provider"]
  node_api_routes["API Routes<br/>rest routes<br/>[api.php]"]
  node_ajax_routes["Ajax Routes<br/>[ajax.php]"]
  node_admin_menu["Admin Menu<br/>menu integration<br/>[Menu.php]"]
  node_middleware{{"Middleware<br/>request guards"}}
  node_views["Views<br/>php templates<br/>[Layout.php]"]
  node_migrations[("Migrations<br/>schema versions<br/>[PluginOptions.php]")]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["Frontend App<br/>react app<br/>[main.tsx]"]
  node_welcome_screen["Welcome<br/>ui screen<br/>[Welcome.tsx]"]
  node_runtime_config["Runtime Config<br/>frontend config<br/>[config.ts]"]
  node_request_helper["Requests<br/>api client<br/>[request.ts]"]
end

subgraph group_tooling["Tooling"]
  node_cli["wp-kit CLI<br/>scaffolding cli"]
  node_dev_env["Dev Env<br/>wp-env setup<br/>[.wp-env.json]"]
  node_ci["CI Checks<br/>automation<br/>[ci.yml]"]
end

node_plugin_root -->|"loads"| node_backend_bootstrap
node_backend_bootstrap -->|"starts"| node_plugin_core
node_plugin_core -->|"uses"| node_config
node_plugin_core -->|"loads"| node_dotenv
node_plugin_core -->|"registers"| node_hook_provider
node_plugin_core -->|"registers"| node_installer_provider
node_hook_provider -->|"mounts"| node_api_routes
node_hook_provider -->|"mounts"| node_ajax_routes
node_hook_provider -->|"guards"| node_middleware
node_hook_provider -->|"adds"| node_admin_menu
node_hook_provider -->|"renders"| node_views
node_installer_provider -->|"runs"| node_migrations
node_api_routes -->|"serves"| node_request_helper
node_ajax_routes -->|"serves"| node_request_helper
node_frontend_app -->|"shows"| node_welcome_screen
node_frontend_app -->|"reads"| node_runtime_config
node_frontend_app -->|"calls"| node_request_helper
node_cli -->|"scaffolds"| node_backend_bootstrap
node_cli -->|"generates"| node_migrations
node_dev_env -.->|"hosts"| node_frontend_app
node_dev_env -.->|"activates"| node_plugin_root
node_ci -.->|"verifies"| node_plugin_core
node_ci -.->|"verifies"| node_frontend_app
node_ci -.->|"verifies"| node_cli

click node_backend_bootstrap "https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/bootstrap.php"
click node_plugin_core "https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Plugin.php"
click node_config "https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Config.php"
click node_dotenv "https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Dotenv.php"
click node_hook_provider "https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Providers/HookProvider.php"
click node_installer_provider "https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Providers/InstallerProvider.php"
click node_api_routes "https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/hooks/api.php"
click node_ajax_routes "https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/hooks/ajax.php"
click node_admin_menu "https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/src/Menu.php"
click node_middleware "https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/HTTP/Middleware/NonceCheckerMiddleware.php"
click node_views "https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Views/Layout.php"
click node_migrations "https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/db/Migrations/PluginOptions.php"
click node_frontend_app "https://github.com/csemazharul/wp-plugin-starter/blob/main/frontend/src/main.tsx"
click node_welcome_screen "https://github.com/csemazharul/wp-plugin-starter/blob/main/frontend/src/Welcome.tsx"
click node_runtime_config "https://github.com/csemazharul/wp-plugin-starter/blob/main/frontend/src/config/config.ts"
click node_request_helper "https://github.com/csemazharul/wp-plugin-starter/blob/main/frontend/src/common/helpers/request.ts"
click node_cli "https://github.com/csemazharul/wp-plugin-starter/tree/main/wp-kit"
click node_dev_env "https://github.com/csemazharul/wp-plugin-starter/blob/main/.wp-env.json"
click node_ci "https://github.com/csemazharul/wp-plugin-starter/blob/main/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin_root toneBlue
class node_backend_bootstrap,node_plugin_core,node_config,node_dotenv,node_hook_provider,node_installer_provider,node_api_routes,node_ajax_routes,node_admin_menu,node_middleware,node_views,node_migrations toneAmber
class node_frontend_app,node_welcome_screen,node_runtime_config,node_request_helper toneMint
class node_cli,node_dev_env,node_ci toneRose
```

## Components

### WordPress Runtime

Plugin lifecycle and request handling inside WordPress.

- **Plugin Shell**: wordpress plugin · Top-level plugin boundary loaded by WordPress.

### Backend

PHP bootstrap, lifecycle, routing, views, and persistence.

- [Bootstrap](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/bootstrap.php): php entry · Backend entry point that wires plugin startup. · `backend/bootstrap.php`
- [Plugin Core](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Plugin.php): app kernel · Central plugin composition and runtime wiring. · `backend/app/Plugin.php`
- [Config](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Config.php): settings · Backend configuration and environment access. · `backend/app/Config.php`
- [Dotenv](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Dotenv.php): env loader · Loads runtime environment values for the plugin. · `backend/app/Dotenv.php`
- [Hooks](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Providers/HookProvider.php): provider · Registers WordPress hooks and application routes. · `backend/app/Providers/HookProvider.php`
- [Installer](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Providers/InstallerProvider.php): provider · Handles activation, uninstall, and migrations. · `backend/app/Providers/InstallerProvider.php`
- [API Routes](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/hooks/api.php): rest routes · REST endpoints exposed through WPKit routing. · `backend/hooks/api.php`
- [Ajax Routes](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/hooks/ajax.php): ajax routes · AJAX endpoints exposed through WPKit routing. · `backend/hooks/ajax.php`
- [Admin Menu](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/src/Menu.php): menu integration · Registers the WordPress admin entry point. · `backend/app/src/Menu.php`
- [Middleware](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/HTTP/Middleware/NonceCheckerMiddleware.php): request guards · Security and authorization checks for requests. · `backend/app/HTTP/Middleware/NonceCheckerMiddleware.php`
- [Views](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/app/Views/Layout.php): php templates · Server-side layout and shell composition for the admin UI. · `backend/app/Views/Layout.php`
- [Migrations](https://github.com/csemazharul/wp-plugin-starter/blob/main/backend/db/Migrations/PluginOptions.php): schema versions · Versioned database changes and rollback support. · `backend/db/Migrations/PluginOptions.php`

### Frontend

React/Vite app embedded in the plugin UI.

- [Frontend App](https://github.com/csemazharul/wp-plugin-starter/blob/main/frontend/src/main.tsx): react app · Vite-built React application embedded in WordPress. · `frontend/src/main.tsx`
- [Welcome](https://github.com/csemazharul/wp-plugin-starter/blob/main/frontend/src/Welcome.tsx): ui screen · Default frontend screen and app landing view. · `frontend/src/Welcome.tsx`
- [Runtime Config](https://github.com/csemazharul/wp-plugin-starter/blob/main/frontend/src/config/config.ts): frontend config · Bridges server-provided values into the client app. · `frontend/src/config/config.ts`
- [Requests](https://github.com/csemazharul/wp-plugin-starter/blob/main/frontend/src/common/helpers/request.ts): api client · Client helper for calling plugin endpoints. · `frontend/src/common/helpers/request.ts`

### Tooling

CLI, development environment, and quality gates.

- [wp-kit CLI](https://github.com/csemazharul/wp-plugin-starter/tree/main/wp-kit): scaffolding cli · Plugin initialization and code generation commands. · `wp-kit`
- [Dev Env](https://github.com/csemazharul/wp-plugin-starter/blob/main/.wp-env.json): wp-env setup · Docker-based WordPress development environment. · `.wp-env.json`
- [CI Checks](https://github.com/csemazharul/wp-plugin-starter/blob/main/.github/workflows/ci.yml): automation · Automated validation for PHP, frontend, and browser tests. · `.github/workflows/ci.yml`

## Connections

- Plugin Shell → Bootstrap: loads · WordPress loads the plugin backend entry point.
- Bootstrap → Plugin Core: starts · Bootstrap initializes the plugin kernel.
- Plugin Core → Config: uses · Core wiring reads plugin configuration.
- Plugin Core → Dotenv: loads · Environment values are loaded during startup.
- Plugin Core → Hooks: registers · Registers hook and route providers.
- Plugin Core → Installer: registers · Registers installation and lifecycle provider.
- Hooks → API Routes: mounts · Hook provider mounts REST routes.
- Hooks → Ajax Routes: mounts · Hook provider mounts AJAX routes.
- Hooks → Middleware: guards · Routes are protected by middleware checks.
- Hooks → Admin Menu: adds · Registers the admin menu entry.
- Hooks → Views: renders · Admin UI shell is assembled from PHP views.
- Installer → Migrations: runs · Install and uninstall lifecycle manages schema migrations.
- API Routes → Requests: serves · Frontend calls into REST endpoints.
- Ajax Routes → Requests: serves · Frontend calls into AJAX endpoints.
- Frontend App → Welcome: shows · Main UI starts on the welcome screen.
- Frontend App → Runtime Config: reads · Client bootstraps with server-provided config.
- Frontend App → Requests: calls · UI interacts with backend through request helpers.
- wp-kit CLI → Bootstrap: scaffolds · CLI initializes and updates plugin backend structure.
- wp-kit CLI → Migrations: generates · CLI generates backend migration files.
- Dev Env → Frontend App: hosts · Local environment runs the frontend alongside WordPress.
- Dev Env → Plugin Shell: activates · Development environment auto-activates the plugin.
- CI Checks → Plugin Core: verifies · CI validates backend quality gates.
- CI Checks → Frontend App: verifies · CI validates frontend quality gates.
- CI Checks → wp-kit CLI: verifies · CI covers scaffolding and tooling behavior.