Architecture Overview

Architecture Overview

Directory Structure

openwp/
├── openwp.php              # Plugin entry point, defines constants
├── constants.php           # All OPENWP_* constants
├── loader.php              # PSR-4 autoloader, boot sequence
├── webpack.config.js       # 3 entry points (admin, editor, chatbot)
├── tailwind.config.js      # Custom design tokens
├── package.json            # Node dependencies
├── composer.json           # PHP dependencies & scripts
│
├── inc/                    # PHP backend (PSR-4: OpenWP\Inc\*)
│   ├── Actions/            # Action handlers + registry + executor
│   ├── Abilities/          # WordPress Abilities API bridge
│   ├── Admin/              # Admin page + editor block registration
│   ├── Agent/              # Agent_Engine - prompt orchestration
│   ├── API/                # REST controllers + SSE streaming
│   ├── Backup/             # Pre-action SQL snapshots + restore
│   ├── Chatbot/            # Attachment service for chatbot uploads
│   ├── Core/               # Action_Bootstrap + Settings
│   ├── Database/           # Migrations + Tables helper
│   ├── Frontend/           # Sitewide chatbot widget
│   ├── Logs/               # Audit log + approval queue + rollback
│   ├── MCP/                # MCP server (SSE + HTTP transports)
│   ├── Memory/             # Agent memory CRUD + guard
│   ├── Onboarding/         # First-run onboarding state
│   ├── Permissions/        # Capability_Manager
│   ├── Providers/          # LLM clients (4 providers)
│   ├── Security/           # PolicyEngine, Sql_Guard, Rate_Limiter, encryption
│   ├── Traits/             # Get_Instance singleton trait
│   └── Utils/              # Schema_Validator
│
├── src/                    # JavaScript frontend
│   ├── admin/              # Admin dashboard SPA
│   │   ├── app.jsx         # Root component with all state
│   │   ├── screens/        # Tab screens (10 screens)
│   │   ├── components/     # UI components + shadcn primitives
│   │   ├── hooks/          # use-hash-tab.js
│   │   └── lib/            # Utilities
│   ├── editor/             # Gutenberg block
│   │   ├── blocks/         # ai-content-generator block
│   │   ├── components/     # Toolbar, preview, progress, prompt
│   │   └── hooks/          # use-streaming-generation.js
│   ├── shared/             # Shared between admin + editor
│   │   ├── api.js          # request(), streamRequest(), uploadRequest()
│   │   ├── constants.js    # Tab keys, onboarding routes
│   │   └── utils.js        # Shared utilities
│   ├── sitewide-chatbot/   # Frontend chatbot widget
│   └── assets/             # Icons
│
├── build/                  # Compiled assets (wp-scripts output)
└── vendor/                 # Composer dependencies

Core Design Principles

1. No dynamic PHP execution - All actions must be pre-registered in Action_Registry
2. Singleton everywhere - All service classes use the Get_Instance trait
3. Strict JSON contract - LLM must return {thought, action, params, confidence}
4. Risk-stratified execution - Four risk levels with escalating guardrails
5. Full audit trail - Every action logged with rollback capability

Request Flow

User Prompt
    │
    ▼
OpenWP_Controller (REST API)
    │
    ▼
Agent_Engine
    ├── Build system prompt (ACTION_CATALOG + SITE_CONTEXT + MEMORY)
    ├── Send to LLM Provider (streaming or sync)
    ├── Parse JSON response
    └── Validate against Action_Registry
         │
         ▼
    Action_Executor
    ├── Schema validation (Schema_Validator)
    ├── Policy evaluation (PolicyEngine)
    │   ├── Capability check
    │   ├── Action enabled check
    │   └── Approval requirement check
    ├── Backup creation (if required)
    ├── Execute action callback
    └── Log result (Log_Repository)
         │
         ▼
    Response to frontend (JSON or SSE stream)

Key Patterns

Singleton Pattern

All PHP services use Get_Instance trait:

use OpenWP\Inc\Traits\Get_Instance;

class MyService {
    use Get_Instance;

    private function __construct() {
        // initialization
    }
}

// Usage
MyService::get_instance();

Action Registration Pattern

New actions go in inc/Actions/ handler classes, registered in Action_Bootstrap:

$this->register(
    'action_key',           // Unique action identifier
    [Handler::class, 'method'],  // Callback
    'edit_posts',           // Required capability
    'low',                  // Risk level: low|medium|high|critical
    true,                   // Mutates data?
    false,                  // Requires pre-action backup?
    $schema,                // JSON input schema
    'openwp/category',      // Domain category
    $output_schema          // JSON output schema
);