# CLAUDE.md

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

## Project Overview

This is a WordPress/WooCommerce plugin called "Stock Message For WooCommerce" that enables customers to receive email notifications when out-of-stock products become available again. The plugin supports simple, variable, and grouped products.

**Key Features:**
- Customizable "Notify Me" buttons for out-of-stock products
- Email subscription system with optional verification
- reCAPTCHA integration for form security
- Automated back-in-stock email notifications via cron jobs
- Admin subscriber management dashboard

## Architecture

### Core Components

The plugin follows WordPress plugin architecture patterns with a class-based structure:

- **Main Plugin File:** `trunk/stock-message-for-woocommerce.php` - Plugin registration, activation hooks, and initialization
- **Core Class:** `includes/class-stock-message-for-woocommerce.php` - Main plugin orchestrator, initializes all components
- **Settings Management:** `includes/class-stock-message-for-woocommerce-settings.php` - Admin settings page and configuration
- **Product Type Handlers:** 
  - `includes/class-stock-message-for-woocommerce-simple-product.php`
  - `includes/class-stock-message-for-woocommerce-variable-product.php`
  - `includes/class-stock-message-for-woocommerce-grouped-product.php`
- **Helper Functions:** `includes/class-stock-message-for-woocommerce-helpers.php` - Utility methods and button generation
- **Notifications:** `includes/class-stock-message-for-woocommerce-notifications.php` - Email sending logic
- **Cron Jobs:** `includes/class-stock-message-for-woocommerce-cron.php` - Background stock monitoring
- **Subscriber Management:** `includes/class-stock-message-for-woocommerce-subscribers-table.php`

### Settings Structure

Settings are organized into separate classes under `includes/settings/`:
- `class-stock-message-button-settings.php` - Button appearance and behavior
- `class-stock-message-form-settings.php` - Subscription form configuration  
- `class-stock-message-email-settings.php` - Email template and verification settings

### Database Schema

The plugin creates a custom table `wp_stock_messages` on activation:
- `id` - Primary key
- `product_id` - WooCommerce product ID
- `email` - Subscriber email address
- `created_at` - Subscription timestamp
- Index on `(product_id, email)` for efficient lookups

### Frontend Assets

- **CSS:** `css/stock-message.css` - Main frontend styles
- **JavaScript:** `js/stock-message.js` - Frontend form handling and AJAX
- **Admin Assets:** Separate CSS/JS files for admin functionality

### Hooks and Integration

The plugin integrates with WooCommerce through:
- Product display hooks to show notification buttons
- Stock status change hooks to trigger notifications
- WooCommerce settings integration
- Custom order tables compatibility declaration

## Development Commands

This plugin uses traditional WordPress development patterns without modern build tools.

### Translation Management
```bash
# Generate/update translation files (requires WP-CLI)
wp i18n make-pot . languages/stock-message-for-woocommerce.pot --domain=stock-message-for-woocommerce
```

### WordPress Development
```bash
# Activate plugin (if working in WordPress environment)
wp plugin activate stock-message-for-woocommerce

# Check plugin status
wp plugin status stock-message-for-woocommerce

# Run cron jobs manually for testing
wp cron event run stock_message_for_woocommerce_cron_hook
```

## File Structure

```
trunk/                          # Main plugin files
├── stock-message-for-woocommerce.php  # Main plugin file
├── uninstall.php              # Cleanup on plugin removal
├── includes/                  # PHP classes
│   ├── class-stock-message-for-woocommerce.php  # Main class
│   ├── class-stock-message-for-woocommerce-*.php  # Component classes
│   └── settings/              # Settings page classes
├── css/                       # Stylesheets
├── js/                        # JavaScript files
├── languages/                 # Translation files
└── img/                       # Plugin assets

tags/                          # Released versions
assets/                        # WordPress.org plugin assets
```

## Important Notes

- **Version Control:** Uses SVN for WordPress.org repository (not Git)
- **WordPress Version:** Requires WordPress 5.0+, PHP 7.0+
- **WooCommerce:** Requires WooCommerce 3.0+, tested up to 9.6
- **Database:** Custom table created on activation, dropped on uninstall
- **Text Domain:** `stock-message-for-woocommerce`
- **Cron Jobs:** Plugin schedules background tasks for stock monitoring
- **AJAX:** Uses WordPress AJAX for subscriber management and form submissions

## Security Considerations

- All AJAX requests use WordPress nonces for security
- Database queries use prepared statements
- Email addresses are validated before storage
- reCAPTCHA integration available for form protection
- Proper capability checks for admin functions