# 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 plugin called "SEO AI Audit Tool" that provides AI-powered SEO auditing and optimization features. The plugin integrates with Google Search Console and Ahrefs to analyze website content, keywords, and backlinks.

## Development Commands

### WordPress Plugin Development
This is a traditional WordPress plugin without modern build tools. Files are served directly without compilation.

**Debug Mode**: Enable debugging by setting `seoaudp_debug_enabled` option to `true` in WordPress admin, which activates:
- PHP error reporting and logging
- WordPress debug constants (WP_DEBUG, WP_DEBUG_LOG)
- Enhanced logging via `seoaudp_log()` function

**Database Operations**:
- Plugin activation creates/migrates database tables automatically
- Database version controlled by `SEOAUDP_DB_VERSION` constant (currently 1.7)
- Manual table recreation: deactivate and reactivate plugin

**File Versioning**: Assets use `seoaudp_get_file_version()` to append file modification timestamps when `SEOAUDP_PLUGIN_BETA_VERSION` is true

### Testing & Validation
- No automated test suite present
- Manual testing required for all changes
- Test in WordPress environment with various themes and plugins

## Architecture & Structure

### Core Pattern & Initialization
- **MVC Architecture**: Follows Model-View-Controller pattern with WordPress hooks integration
- **Namespace**: All classes use `SEO_Audit_Tool` namespace
- **Initialization**: Plugin uses `SEO_Audit_Loader` class to register WordPress hooks and filters
- **Class Dependencies**: Main plugin file checks for required class existence before initialization

### Entry Points
- `seo-ai-audit-tool.php` - Main plugin file with constants, activation hooks, and class loading
- `functions.php` - Global utility functions for security (wp_kses), file versioning, and HTML sanitization

### Core MVC Components
- **Models**: `includes/models/` - Data processing, SEO analysis logic, and CRO auditing
- **Views**: `includes/views/` - HTML rendering, UI components, and template partials
- **Controllers**: `includes/controllers/class-seo-audit-controller.php` - Admin pages, AJAX handling, user interactions

### Key Components
- **Database Layer**: `includes/class-seo-audit-db.php` - Custom database tables and queries
- **Loader System**: `includes/class-seo-audit-loader.php` - WordPress hooks and filters management
- **AJAX Handler**: `includes/class-seo-audit-ajax.php` - AJAX request processing
- **Settings**: `includes/class-seo-audit-settings-page.php` - Plugin configuration

### Feature Modules
- **Magic Keyword Finder**: `includes/class-seo-audit-magic-keyword-finder.php`
- **Magic CTR Booster**: `includes/class-seo-audit-magic-ctr-booster.php`
- **Backlinks Analyzer**: `includes/class-seo-audit-backlinks-analyzer.php`
- **Bulk Fix Dashboard**: `includes/class-seo-bulk-fix-dashboard.php`
- **AI Bot Optimizer**: `includes/class-seo-audit-ai-bot-optimizer.php`
- **Prune Page Finder**: `includes/class-seo-audit-prune-page-finder.php`

### Supporting Components
- **Services**: `includes/services/class-search-intent-calculator.php`
- **Utils**: `includes/utils/` - Helper classes for specific functionality
- **Helpers**: `includes/helpers/class-html-renderer.php`
- **Traits**: `includes/traits/trait-seo-audit-hex-handler.php`

## Database Structure

The plugin creates custom database tables:
- `wp_seoaudp_focus_pages` - Stores focus page selections
- `wp_seoaudp_ahrefs_keywords` - Ahrefs keyword data
- `wp_seoaudp_gsc_data` - Google Search Console data
- Additional tables for AI responses, backlinks, etc.

Database version managed via `SEOAUDP_DB_VERSION` constant.

## Constants & Configuration

Key constants defined in main plugin file:
- `SEOAUDP_PLUGIN_DIR` - Plugin directory path
- `SEOAUDP_PLUGIN_URL` - Plugin URL
- `SEOAUDP_PLUGIN_VERSION` - Current version (1.1.1)
- `SEOAUDP_DB_VERSION` - Database schema version
- `SEOAUDP_DEBUG_ENABLED` - Debug mode toggle

## Assets & Frontend

### JavaScript
- `assets/js/seoaudp-script.js` - Main dashboard functionality
- `assets/js/seoaudp-ctr-script.js` - CTR booster features
- `assets/js/seoaudp-bulk-fix.js` - Bulk fix dashboard
- `assets/js/seoaudp-backlinks-analyzer.js` - Backlinks analysis
- Uses DataTables library for table management

### CSS
- `assets/css/seoaudp-style.css` - Main plugin styles
- `assets/css/seoaudp-bulk-fix.css` - Bulk fix specific styles

### Third-party Libraries
- DataTables (jQuery plugin) for advanced table functionality
- JSZip for Excel export functionality
- Chart.js for data visualization

## Security & Code Standards

### Security Implementation
- **AJAX Security**: All AJAX requests require WordPress nonces for CSRF protection
- **Permission Checks**: Functions verify `current_user_can('manage_options')` for admin access
- **Input Sanitization**: Uses WordPress methods (`sanitize_text_field()`, etc.)
- **Output Escaping**: Custom `seoaudp_get_allowed_html()` function provides comprehensive wp_kses rules including SVG support

### WordPress Integration Standards  
- **Coding Standards**: Follows WordPress Coding Standards
- **Object-Oriented**: Namespaced classes with dependency injection
- **Hook Architecture**: WordPress actions/filters managed through loader system
- **Database**: Custom tables with proper WordPress table naming conventions (`wp_seoaudp_*`)

### Error Handling & Debugging
- **Logging**: `seoaudp_log()` function for debug output when `SEOAUDP_DEBUG_ENABLED` is true
- **Exception Handling**: Try-catch blocks for database operations and API calls
- **Activation Safety**: Plugin checks for required classes before initialization to prevent fatal errors

## Key Features

1. **SEO Auditing** - Analyzes pages for SEO compliance
2. **AI Integration** - Uses OpenAI API for content analysis (E-A-T scoring)
3. **Data Import** - GSC and Ahrefs CSV data import
4. **Focus Pages** - Priority page management system
5. **Keyword Analysis** - Search intent calculation and optimization
6. **Backlinks Analysis** - Link profile evaluation
7. **Bulk Operations** - Mass SEO fixes and updates

## WordPress Integration

- Admin menu integration under "SEO AI Audit Tool"
- Custom post columns for SEO data
- Meta box integration for individual pages
- WordPress REST API endpoints for data exchange
- Compatible with Yoast SEO (stores focus keywords in Yoast meta fields)

## Plugin Lifecycle & Data Management

### Activation & Updates
- **Database Setup**: Automatically creates custom tables and runs version-specific migrations
- **Version Control**: Database schema versioned via `SEOAUDP_DB_VERSION` constant
- **Migration System**: Handles upgrades by comparing installed vs. current DB version
- **First Run**: Stores activation timestamp in `seoaudp_first_activation` option

### Data Persistence  
- **Custom Tables**: Plugin data stored in dedicated tables (`wp_seoaudp_*`)
- **WordPress Options**: Settings and configuration stored via WordPress Options API
- **Cleanup**: Minimal deactivation cleanup - tables and data persist after deactivation
- **Uninstall**: No uninstall hook implemented (intentional data preservation)