Frontend Architecture

Frontend Architecture

OpenWP's frontend is built with React 18, Tailwind CSS 3.4, and Radix UI primitives. It consists of three webpack entry points.

Build System

Webpack Entry Points (webpack.config.js)

entry: {
    index: './src/admin/index.js',                          // Admin dashboard SPA
    'ai-content-generator-block': './src/editor/index.js',  // Gutenberg block
    'sitewide-chatbot': './src/sitewide-chatbot/index.js',  // Frontend chatbot widget
}

Build Commands

npm run start          # Dev build with hot reload
npm run build          # Production build
npm run lint:js        # Lint JavaScript
npm run lint:css       # Lint CSS
npm run format         # Format source files

Path Alias

jsconfig.json maps src/* to ./src/* for clean imports.

Technology Stack

Library	Version	Purpose
React	^18.3.1	UI framework
Tailwind CSS	^3.4.17	Utility-first CSS
Radix UI	Various	Accessible primitives
Lucide React	^0.575.0	Icons
Sonner	^2.0.7	Toast notifications
CVA	^0.7.1	Component variant styling
clsx + tailwind-merge	Latest	Conditional class names
@wordpress/scripts	^30.0.0	Build tooling
@wordpress/api-fetch	Bundled	REST API client

Tailwind Configuration

Custom design tokens in tailwind.config.js:

Token	Value	Usage
primary	#0057ff	Primary brand color
accent	#ff7d1f	Accent color
ink	Custom	Text color
muted	Custom	Muted text
line	Custom	Borders
surface	Custom	Card backgrounds
bg	Custom	Page backgrounds
success	Custom	Success states
warning	Custom	Warning states
danger	Custom	Error states

Font: Archivo Preflight: Disabled (for WordPress admin compatibility)

Admin Dashboard SPA (src/admin/)

Root Component (app.jsx)

The main app component manages all state via React hooks (no external state library). It handles:

• Tab navigation (hash-based routing)
• Settings management
• Provider configuration
• Onboarding flow

Screens (src/admin/screens/)

Screen	File	Description
Dashboard	screens/dashboard/index.jsx	Stats, quick actions, recommended plugins
Console	screens/console/index.jsx	Chat-style AI agent interface
Approvals	screens/approvals/index.jsx	Pending action approval queue
Settings	screens/settings/index.jsx	Plugin configuration
Actions	screens/actions/index.jsx	Action catalog and policy management
Memory	screens/memory/index.jsx	Agent memory viewer/editor
Logs	screens/logs/index.jsx	Audit log browser
Backups	screens/backups/index.jsx	Backup management and restore
Onboarding	screens/onboarding/index.jsx	First-run setup wizard

Onboarding Steps

1. Welcome (steps/welcome.jsx) - Introduction
2. Provider (steps/provider.jsx) - API key setup
3. Guardrails (steps/guardrails.jsx) - Risk/approval settings
4. Test Command (steps/test-command.jsx) - Verify setup
5. Done (steps/done.jsx) - Completion

UI Components (src/admin/components/)

shadcn-style primitives built on Radix UI:

• Button, Dialog, Select, Table, Input, Textarea
• Switch, Badge, Alert, Card, Tooltip
• Accordion, NavigationMenu, Progress, Skeleton
• Label, RadioGroup, Separator, Sonner (toasts)

Custom components:

• Header - Page header with navigation
• SideNav - Sidebar navigation
• NavBar - Top navigation bar
• Panel - Content panel wrapper
• StatCard - Dashboard statistics
• Pill - Status badges
• SmartResult - AI response renderer
• JsonBox - JSON viewer

Hooks

• use-hash-tab.js - Hash-based tab routing (#console, #settings, etc.)

Editor Block (src/editor/)

AI Content Generator Block

Registered in src/editor/blocks/ai-content-generator/:

• index.js - Block registration
• edit.jsx - Block edit component

Components

• ai-block-toolbar.jsx - Block toolbar actions
• prompt-box.jsx - Prompt input with send button
• generation-preview.jsx - Live content preview
• generation-progress.jsx - Progress indicator
• ai-modify-popover.jsx - Modify/refine popover
• badge-selector.jsx - Content type/tone selector
• global-modal.jsx - Modal dialog for AI operations

Hooks

• use-streaming-generation.js - SSE streaming hook for content generation

Block Recovery

• utils/recover-blocks.js - Handles block validation/recovery

Sitewide Chatbot (src/sitewide-chatbot/)

Frontend chatbot widget for public-facing pages:

• index.js - Entry point and initialization
• widget.jsx - Chat widget component

Shared Code (src/shared/)

API Client (api.js)

Three methods for REST API communication:

// Standard request (via @wordpress/api-fetch)
import { request } from 'src/shared/api';
const data = await request('/openwp/v1/bootstrap');

// SSE streaming request
import { streamRequest } from 'src/shared/api';
await streamRequest('/openwp/v1/agent/execute/stream', body, (event) => {
    // Handle typed events
});

// File upload
import { uploadRequest } from 'src/shared/api';
const result = await uploadRequest('/openwp/v1/chatbot/upload', formData);

Runtime Configuration

The API client resolves configuration from multiple sources (in priority order):

1. options.runtime - Explicitly passed config
2. window.openwpSiteChat - Sitewide chatbot config
3. window.openwpAdmin - Admin page config (nonce, root URL, onboarding state, capabilities)
4. window.wpApiSettings - WordPress default

Constants (constants.js)

Tab keys, onboarding route constants, OpenRouter model list.