# CLAUDE.md

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

## Project Overview

HVAC Community Events is a WordPress plugin extending The Events Calendar (TEC) suite to create a trainer community platform. It provides custom user roles (`hvac_trainer`, `hvac_master_trainer`), event management, certificate generation, venue/organizer management, and Zoho CRM integration.

- **Entry Point**: `hvac-community-events.php`
- **Core Classes**: `includes/class-*.php` (all use singleton pattern)
- **Templates**: `templates/page-*.php`
- **TEC Integration**: Events, venues, organizers via The Events Calendar suite

## Commands

### Deployment
```bash
# Pre-deployment validation (ALWAYS run first)
scripts/pre-deployment-check.sh

# Deploy to staging
scripts/deploy.sh staging

# Deploy to production (requires explicit user request and confirmation)
scripts/deploy.sh production
```

### Testing
```bash
# Start Docker test environment
docker compose -f tests/docker-compose.test.yml up -d

# E2E tests (headless)
HEADLESS=true BASE_URL=http://localhost:8080 node test-master-trainer-e2e.js
HEADLESS=true BASE_URL=http://localhost:8080 node test-comprehensive-validation.js

# E2E tests (headed - requires display)
DISPLAY=:0 XAUTHORITY=/run/user/1000/.mutter-Xwaylandauth.U8VEB3 node test-master-trainer-e2e.js
```

### WordPress CLI (on server via SSH)
```bash
wp rewrite flush
wp eval 'HVAC_Page_Manager::create_required_pages();'
wp eval 'wp_set_password("Password123", USER_ID);'  # Reset password (more reliable than wp user update)
```

### Staging Environment
```bash
# SSH access
ssh roodev@146.190.76.204
cd /home/974670.cloudwaysapps.com/uberrxmprk/public_html

# Test account (staging)
Username: test_master | Password: TestPass123 | Role: hvac_master_trainer
```

## Architecture

### Singleton Pattern (MANDATORY)
All core classes use the singleton pattern. Never assume static methods exist:

```php
// CORRECT
echo HVAC_Breadcrumbs::instance()->render_breadcrumbs();
HVAC_Venues::instance()->get_venues();

// WRONG - will fail
HVAC_Breadcrumbs::render();
```

### Template Requirements
All page templates MUST include:
```php
<?php
defined('ABSPATH') || exit;
define('HVAC_IN_PAGE_TEMPLATE', true);
get_header();
// ... content ...
get_footer();
```

### Security Patterns
```php
// Input sanitization
$trainer_id = absint($_POST['trainer_id']);
$email = sanitize_email($_POST['email']);

// Output escaping
echo esc_html($trainer_name);
echo esc_url($profile_url);

// Nonce verification
wp_verify_nonce($_POST['nonce'], 'hvac_action');

// Role checking (use roles, not capabilities)
$user = wp_get_current_user();
if (!in_array('hvac_trainer', $user->roles)) {
    wp_die('Access denied');
}
```

### File Structure
```
includes/
├── class-hvac-plugin.php          # Main controller (singleton)
├── class-hvac-shortcodes.php      # Shortcode management
├── class-hvac-scripts-styles.php  # Asset management
├── class-hvac-route-manager.php   # URL routing
├── class-hvac-venues.php          # Venue CRUD (singleton)
├── class-hvac-organizers.php      # Organizer management (singleton)
├── class-hvac-training-leads.php  # Lead tracking (singleton)
├── admin/                         # Admin classes
├── certificates/                  # Certificate generation
├── communication/                 # Email templates
├── zoho/                          # Zoho CRM integration
└── find-trainer/                  # Public trainer directory

templates/page-*.php               # Page templates (hierarchical URLs)
assets/{css,js}/                   # Frontend assets
tests/                             # Docker environment and E2E tests
scripts/                           # Deployment and maintenance scripts
```

### URL Structure
- Trainer: `/trainer/dashboard/`, `/trainer/event/manage/`, `/trainer/certificate-reports/`
- Master Trainer: `/master-trainer/dashboard/`, `/master-trainer/trainers/`
- Public: `/training-login/`, `/find-a-trainer/`

## Critical Warnings

### NEVER Do
- Deploy to production without explicit user request
- Skip pre-deployment validation (`scripts/pre-deployment-check.sh`)
- Use static method calls without verifying singleton pattern
- Re-enable monitoring infrastructure (causes PHP segmentation faults)

### Disabled Systems (DO NOT RE-ENABLE)
The following monitoring systems are PERMANENTLY DISABLED due to causing PHP segmentation faults:
`HVAC_Background_Jobs`, `HVAC_Health_Monitor`, `HVAC_Error_Recovery`, `HVAC_Security_Monitor`, `HVAC_Performance_Monitor`, `HVAC_Backup_Manager`, `HVAC_Cache_Optimizer`

## Zoho CRM Integration

Located in `includes/zoho/`. Maps WordPress data to Zoho CRM:
- Events → Campaigns
- Trainers → Contacts
- Attendees → Contacts + Campaign Members
- RSVPs → Leads + Campaign Members

**Admin Page**: `/wp-admin/admin.php?page=hvac-zoho-sync`

**Important**: Staging environment blocks all write operations to Zoho CRM. Only production can sync data.

## Docker Test Environment

```bash
docker compose -f tests/docker-compose.test.yml up -d

# Services:
# WordPress 6.4 (PHP 8.2): http://localhost:8080
# MySQL 8.0: port 3307
# Redis 7: port 6380
# Mailhog: http://localhost:8025
# PhpMyAdmin: http://localhost:8081
```

## Technical Debt

### TEC Community Events Dependency
The plugin still relies on "The Events Calendar: Community" (TEC CE) for event creation/editing forms via `[tribe_community_events]` shortcode. While `HVAC_Event_Manager` has custom CRUD capabilities, production code paths use TEC CE.

**Removal estimate:** 9-14 days of development work.
**Details:** See [docs/reports/TEC-COMMUNITY-EVENTS-DEPENDENCY-ANALYSIS.md](docs/reports/TEC-COMMUNITY-EVENTS-DEPENDENCY-ANALYSIS.md)

**Status:** Deferred - Current implementation is functional and stable.

## Key Documentation

- **[Status.md](Status.md)** - Current project status and recent changes
- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture details
- **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common issues and solutions
- **[docs/TESTING-GUIDE.md](docs/TESTING-GUIDE.md)** - Testing procedures