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

AI Assistant Tools

Zen MCP Tools (Use Throughout Every Session)

• Zen Debug: Use whenever you encounter an error or unexpected behavior
• Zen Code Review: Use whenever you finish a significant piece of code or feature
• Zen Analyze: Use before adding new features or making significant changes to existing code
• Zen Deepthink: Use when you have a complex problem to solve or need to brainstorm ideas
• Zen Chat: Use for general questions, clarifications, or when you need assistance with a task

Important Context Reminder: Remind the Zen tools that this is a small local environment with a single user, so security and scalability are not primary concerns.

Clink Multi-Model Workflows (GPT-5, Gemini 3, Kimi K2.5)

Use mcp__zen__clink to get diverse AI perspectives via external CLIs. Available CLIs:

• codex: GPT-5 - Fast, precise code understanding
• gemini: Gemini 3 - Large context (1M tokens), thorough analysis
• Kimi K2.5 (via mcp__zen__chat with OpenRouter) - Strong reasoning, excellent at complex logic

Security Warning: Files are sent to OpenAI, Google, and Moonshot AI. NEVER use on .env, credentials, or regulated data.

When to Use Multi-Model:

• Code reviews (catch different types of issues)
• Complex debugging (multiple hypotheses)
• Architecture decisions (diverse perspectives)
• Planning (compare approaches)

Available Skills:

• /multi-review <files> - Code review from all 3 models
• /multi-plan <task> - Planning perspectives from all 3 models
• /multi-debug <issue> - Parallel bug investigation
• /multi-analyze <files> - Comprehensive analysis

Quick Usage (all three calls in one message = parallel execution):

review_prompt = "Review for bugs and security issues"
mcp__zen__clink(prompt=review_prompt, cli_name="codex", role="codereviewer", absolute_file_paths=["/absolute/path/file.py"])
mcp__zen__clink(prompt=review_prompt, cli_name="gemini", role="codereviewer", absolute_file_paths=["/absolute/path/file.py"])
mcp__zen__chat(prompt=review_prompt + " Use Kimi K2.5 via OpenRouter for this analysis.", absolute_file_paths=["/absolute/path/file.py"])

Important: Use absolute paths (not globs). Resolve patterns first: find src -name "*.py" | xargs realpath

Synthesis Format: After multi-model analysis, report:

1. Consensus - All models agree
2. Majority - 2/3 agree (note dissent)
3. Unique insights - Model-specific findings
4. Recommended actions - Prioritized by consensus

Roles: Each CLI supports default, codereviewer, planner