# Moderation API WordPress Plugin - Claude Development Guide

## Overview

This is a WordPress plugin that integrates with the Moderation API service (https://moderationapi.com) to provide automated content moderation for WordPress comments. The plugin automatically analyzes comments using AI to detect various types of harmful content including bullying, discrimination, NSFW content, PII, profanity, spam, and more across 200+ languages.

**Current Version:** 1.0.2  
**Plugin Name:** Moderation API: Automated Content Moderation  
**Text Domain:** moderation-api  
**API Base URL:** https://moderationapi.com  

## Architecture Overview

This plugin follows the WordPress Plugin Boilerplate architecture pattern with clear separation of concerns:

### Core Structure
```
moderation-api.php          # Main plugin bootstrap file
├── includes/               # Core plugin classes
│   ├── class-moderation-api.php                # Main plugin orchestrator
│   ├── class-moderation-api-loader.php         # Hook management
│   ├── class-moderation-api-i18n.php          # Internationalization
│   ├── class-moderation-api-activator.php     # Plugin activation
│   └── class-moderation-api-deactivator.php   # Plugin deactivation
├── admin/                  # Admin-specific functionality
│   ├── class-moderation-api-admin.php         # Admin interface logic
│   ├── views/              # Admin template files
│   ├── css/                # Admin styles
│   └── js/                 # Admin JavaScript
├── public/                 # Public-facing functionality
│   ├── class-moderation-api-public.php        # Public hooks and API integration
│   ├── css/                # Public styles
│   └── js/                 # Public JavaScript
└── languages/              # Translation files
```

### Key Classes and Responsibilities

1. **Moderation_Api** (`includes/class-moderation-api.php`)
   - Main plugin orchestrator
   - Manages dependencies and hook registration
   - Provides utility methods for API key management and view rendering
   - Handles admin notices

2. **Moderation_Api_Admin** (`admin/class-moderation-api-admin.php`)
   - Admin interface management
   - Settings page functionality
   - Custom columns in comments table
   - Admin notices and activation flows

3. **Moderation_Api_Public** (`public/class-moderation-api-public.php`)
   - Comment moderation integration
   - API communication with Moderation API service
   - Webhook handling for async processing
   - Comment duplicate prevention

4. **Moderation_Api_Loader** (`includes/class-moderation-api-loader.php`)
   - WordPress hook management
   - Action and filter registration

## Core Functionality

### Comment Moderation Workflow
1. User submits a comment
2. Plugin hooks into `comment_post` action
3. Comment content is sent to Moderation API for analysis
4. Based on API response, comment is:
   - Auto-approved (if safe)
   - Sent to moderation queue (if flagged)
   - Auto-rejected (if configured)

### Key Features
- **Real-time comment analysis** using AI
- **Multi-language support** (200+ languages)
- **Customizable moderation rules** via Moderation API dashboard
- **Review queue integration** for human oversight
- **Comment metadata tracking** (flags, errors, API responses)
- **Webhook support** for async processing
- **Admin dashboard integration** with custom comment columns

## Development Environment

### Prerequisites
- Docker
- Node.js
- WordPress 5.8+
- PHP 7.4+

### Local Development Setup

The plugin uses `@wordpress/env` for local development:

```bash
# Start the development environment
npx @wordpress/env start

# Access the site
# URL: http://localhost:8888
# Admin: http://localhost:8888/wp-admin
# Username: admin
# Password: password
```

### Configuration Files
- **`.wp-env.json`** - WordPress environment configuration
  - Enables WP_DEBUG and SCRIPT_DEBUG
  - Includes WordPress importer for testing
  - Single-site configuration (multisite: false)

### No Build Process
This plugin does not require a build process:
- No package.json or composer.json
- Direct PHP/CSS/JS development
- Static assets only

## Key Files and Their Purposes

### Main Plugin Files
- **`moderation-api.php`** - Plugin bootstrap, defines constants, handles activation/deactivation
- **`uninstall.php`** - Clean uninstall process (currently basic)
- **`README.txt`** - WordPress.org plugin directory documentation

### Configuration Views (`admin/views/`)
- **`config.php`** - Main settings page template
- **`setup.php`** - Initial setup workflow
- **`activate.php`** - Account activation interface
- **`notice.php`** - Admin notification template

### API Integration
The plugin integrates with Moderation API through:
- **API Key authentication** stored in WordPress options
- **Comment analysis endpoint** for real-time moderation
- **Webhook endpoints** for async processing updates
- **Review queue integration** for manual oversight

## Development Workflow

### Release Process
A bash script (`release-plugin.sh`) handles plugin releases:
1. Reads version from Git tags
2. Updates SVN repository for WordPress.org
3. Creates proper trunk and tag structure
4. Handles asset management

### WordPress.org Submission
- Plugin submitted to WordPress.org plugin directory
- Uses SVN for WordPress.org releases
- Git for development, SVN for distribution

## Testing

### Current State
- **No formal test suite** currently implemented
- **Manual testing** required
- **Test environment** available via wp-env

### Testing Considerations
- Comment moderation workflow
- API integration and error handling
- Admin interface functionality
- Multi-site compatibility (currently disabled)
- Various WordPress versions (tested up to 6.6.2)

## Data Management

### WordPress Options Used
- `moderation_api_key` - Stores API authentication key
- Custom comment meta fields for tracking moderation results

### Comment Metadata
- Flags and moderation status
- API response data
- Error tracking

## Security Considerations

### Current Implementation
- Nonce verification for admin actions (`NONCE = 'modapi-update-key'`)
- Proper escaping in templates
- API key storage in WordPress options
- Webhook endpoint security

### Best Practices Applied
- Direct file access prevention (`ABSPATH` checks)
- Proper WordPress coding standards
- Sanitization and validation patterns

## Integration Points

### WordPress Hooks Used
- `comment_post` - Main comment moderation hook
- `admin_menu` - Admin interface registration
- `admin_init` - Settings initialization
- `manage_edit-comments_columns` - Custom comment columns
- `template_redirect` - Webhook processing

### External Dependencies
- **Moderation API service** - Primary dependency for content analysis
- **WordPress core** - Standard WordPress APIs only
- **No third-party libraries** - Vanilla PHP implementation

## Common Development Tasks

### Adding New Moderation Rules
1. Configure rules in Moderation API dashboard
2. Plugin automatically uses updated rules
3. No code changes required

### Customizing Admin Interface
- Modify files in `admin/views/`
- Update `class-moderation-api-admin.php` for logic
- Add styles to `admin/css/moderation-api-admin.css`

### Debugging Comment Moderation
- Check comment meta for API responses
- Review admin comment columns for flags
- Use WordPress debug logging
- Check webhook endpoint functionality

## Future Enhancement Areas

### Identified Opportunities
- **Automated testing suite** implementation
- **Multi-site support** (currently disabled)
- **Additional content types** (posts, pages, custom post types)
- **Enhanced error handling** and logging
- **Performance optimization** for high-volume sites
- **Bulk moderation tools** for existing comments

### API Expansion
- Support for other content types beyond comments
- Advanced configuration options
- Enhanced webhook processing
- Better error recovery mechanisms

## File Modification Guidelines

### When Working on This Plugin
1. **Follow WordPress coding standards**
2. **Maintain the existing architecture pattern**
3. **Test comment moderation workflow thoroughly**
4. **Update version numbers in `moderation-api.php`**
5. **Update `README.txt` changelog**
6. **Consider backward compatibility**

### Critical Files to Handle Carefully
- `public/class-moderation-api-public.php` - Core moderation logic
- `moderation-api.php` - Plugin bootstrap and constants
- `.wp-env.json` - Development environment configuration

This plugin represents a production WordPress plugin with active users, so changes should be thoroughly tested and follow WordPress development best practices.