upskill-event-manager/CLAUDE.md

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

# 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

# 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)

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

# 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:

// 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
defined('ABSPATH') || exit;
define('HVAC_IN_PAGE_TEMPLATE', true);
get_header();
// ... content ...
get_footer();

Security Patterns

// 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

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

Status: Deferred - Current implementation is functional and stable.

Key Documentation

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