# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

### PHP
```bash
composer fix-all          # Run php-cs-fixer on includes/
composer fix              # Fix only changed files
composer test             # PHPUnit tests
composer code-status      # Dry-run CS check with diff
composer unused-variables # PHPcs variable analysis
```

### Frontend (run from repo root)
```bash
pnpm dev-setup       # First-time setup: installs pnpm, composer, frontend deps
pnpm hot             # Vite dev server with HMR
pnpm production      # Full production build (composer + frontend + packages)
pnpm pda             # Turbo package build + Webpack build
```

### Frontend (run from `frontend-dev/`)
```bash
pnpm hot             # Vite dev server
pnpm build           # Vite build + Gutenberg block + i18n
pnpm build-pkg:prod  # Turbo build all 41 monorepo packages (force)
pnpm lint --fix      # ESLint fix
pnpm i18n:php        # Regenerate languages/generatedString.php
pnpm wp              # Webpack watch (legacy)
```

## Architecture

### PHP Backend

**Entry:** `bitforms.php` → `includes/loader.php` → `includes/Plugin.php` (singleton)

**Core layers:**
- `includes/Core/Hooks/Hooks.php` — central hook registration point
- `includes/Admin/AdminAjax.php` — 30+ `wp_ajax_bitforms_*` AJAX endpoints for all admin operations
- `includes/API/Route/Routes.php` — REST API under namespace `bitform/v1`; controllers in `includes/API/Controller/`
- `includes/Core/Form/FormHandler.php` — dispatches admin/frontend form events; loads Pro overrides if `BITFORMPRO_PLUGIN_DIR_PATH` is defined
- `includes/Core/Database/` — custom Model base class; tables: `wp_bitforms_form`, `wp_bitforms_form_entry`, `wp_bitforms_integration`, `wp_bitforms_email_template`, `wp_bitforms_success_message`, `wp_bitforms_workflow`
- `includes/Frontend/` — renders shortcode/standalone/conversational form views
- `includes/Widgets/` — Elementor and Bricks Builder widget integrations
- `includes/Core/Integration/Integrations.php` — auto-discovers and loads integrations from bitformpro if active
- `includes/Core/Util/` — SmartTags, FileHandler, MailConfig, helpers

**Form lifecycle:**
1. Forms stored as JSON in `bitforms_form.form_content`
2. Rendered via shortcode `[bitform id="N"]`, Gutenberg block, Elementor/Bricks widgets, or standalone page
3. Submission hits `bitforms_form_submission` action → `FrontendFormHandler` → validation → integrations → entry logged to `wp_bitforms_form_entry`

**Pro gating pattern:**
```php
if (class_exists('BitCode\BitFormPro\SomeClass')) { /* pro path */ }
// or
if (defined('BITFORMPRO_PLUGIN_DIR_PATH')) { /* pro path */ }
```

### Frontend (React Admin UI)

**Stack:** React 18 + Vite 4 + Fela (CSS-in-JS) + Jotai (state) + React Router v6 (HashRouter)

**Entry:** `frontend-dev/src/main.jsx` → mounts to `#btcd-app`

**Key directories:**
- `src/components/` — reusable UI components; `CompSettings/` contains per-field settings panels
- `src/pages/` — route-level pages (form builder, entries, integrations, settings)
- `src/GlobalStates/` — Jotai atoms for shared state
- `src/user-frontend/` — user-facing form rendering (separate from admin)
- `src/gutenberg-block/` — Gutenberg block registration

**Monorepo packages** (`frontend-dev/packages/`, 41 packages, Turbo-orchestrated):
- Field packages: `bit-file-up-field`, `bit-phone-number-field`, `bit-rating-field`, `bit-signature-field`, `bit-select-field`, `bit-currency-field`, etc.
- Payment fields: `bit-stripe-field`, `bit-paypal-field`, `bit-razorpay-field`, `bit-mollie-field`
- UI utilities: `bit-multi-step-field`, `bit-repeater-field`, `bit-conditionals`, `bit-helpers`, `atomize-css`

**Build output:** `assets/` at plugin root; PHP reads `assets/manifest.json` for hashed filenames.

**PHP ↔ JS connection:**
- Admin: PHP enqueues Vite output; JS calls `wp.ajax` to `wp_ajax_bitforms_*` actions
- Form frontend: separate webpack build; form config passed via inline JS (`window.bf_*`)