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 system that enables independent trainers to manage their own events, sell tickets, and track performance without accessing the WordPress admin panel. It extends The Events Calendar (TEC) plugin suite with custom functionality for the HVAC training industry.

The system uses a Cloudways staging environment for development and testing, with comprehensive Playwright E2E tests and PHPUnit tests. The project has migrated from Docker-based local development to a staging-only workflow.

Key Commands

Testing

# Run all E2E tests (execute from wordpress-dev/)
npx playwright test --config=playwright.config.ts --reporter=list

# Run complete trainer journey tests
./bin/run-tests.sh --trainer-journey

# Run all tests
./bin/run-tests.sh

# Run specific test types
./bin/run-tests.sh --unit
./bin/run-tests.sh --e2e
./bin/run-tests.sh --integration

# Run specific E2E test suites
./bin/run-tests.sh --e2e --grep @login
./bin/run-tests.sh --e2e --grep @dashboard
./bin/run-tests.sh --e2e --grep @create-event
./bin/run-tests.sh --e2e --grep @event-summary
./bin/run-tests.sh --e2e --grep @modify-event
./bin/run-tests.sh --e2e --grep @certificate

# Run certificate-specific tests
npx playwright test tests/e2e/certificates.test.ts
npx playwright test tests/e2e/certificate-generation-checked-in.test.ts

# Run certificate filtering tests with interactive script
./bin/test-certificate-filter.sh

# Optimize and analyze E2E testing infrastructure
./bin/optimize-e2e-tests.sh

# Run PHPUnit tests on staging
./bin/run-staging-unit-tests.sh
./bin/run-staging-unit-tests.sh --testsuite unit
./bin/run-staging-unit-tests.sh --coverage-html ./coverage-report
./bin/run-staging-unit-tests.sh --filter=test_get_total_events_count

# Setup staging test users and verification
./bin/setup-staging-test-users.sh
./tests/run-tests.sh setup
./tests/run-tests.sh verify
./tests/run-tests.sh teardown --force

Deployment & Staging

# Deploy plugin to staging
./bin/deploy-plugin.sh

# Deploy to production
./deploy.sh --config deploy-config.sh

# Deploy and run tests
./deploy.sh --config deploy-config.sh --run-tests

# Verify staging environment
./bin/verify-staging.sh

# Deploy config to staging
./bin/deploy-config-staging.sh

# Sync data from staging
./bin/sync-staging.sh

# Staging workflow sequence
deploy-config-staging.sh → configure-staging-tests.sh → run-staging-tests.sh

Memory Management System

# Update knowledge graph after deployment
./deploy.sh --config deploy-config.sh --update-memory

# Generate action items after testing
cd tests && ./run-tests.sh --generate-action-items

Architecture Overview

Plugin Structure

The main plugin is "HVAC Community Events" located at: wordpress-dev/wordpress/wp-content/plugins/hvac-community-events/

Required WordPress Plugins

• The Events Calendar (Free)
• Events Calendar Pro
• Event Tickets
• Event Tickets Plus
• The Events Calendar: Community

Environment Configuration

• Uses Cloudways staging server (no local development)
• Environment variables stored in .env file
• Staging URL: https://wordpress-974670-5399585.cloudwaysapps.com/
• SSH access required for staging operations
• PHP memory_limit: 512M minimum

Key Features and Pages

1. Community Registration Page - Trainer account registration with comprehensive profile fields
2. Community Login Page - Branded login experience
3. Trainer Profile Page - Profile management interface
4. Trainer Dashboard - Overview of events and performance metrics
5. Event Summary Page - Detailed event information and attendee data
6. Modify Event Page - Edit existing events
7. Create Event Page - Create new events
8. Email Attendees Page (Phase 2) - Communication with event attendees
9. Order Summary Page (Phase 3) - Ticket purchase details
10. Certificates Report Page - View and manage generated certificates, with filtering by event and attendee
11. Generate Certificates Page - Create PDF certificates for event attendees
12. Request Training Page - Allow trainees to request training
13. My Training Page - Trainee progress tracking

Testing Architecture

1. E2E Tests (Playwright):

   • Located in wordpress-dev/tests/e2e/
   • Configuration: wordpress-dev/playwright.config.ts
   • Supports multiple browsers, mobile emulation
   • Custom reporters (Markdown, HTML)
   • Verbosity control system
   • Test user personas
   • MVP integration testing plan
   • Page Object Model for trainer journey tests:
     • BasePage, LoginPage, DashboardPage
     • CreateEventPage, EventSummaryPage, ModifyEventPage
     • CertificatePage, ProfilePage
   • Trainer Journey Test Suite covering steps 1-8 of user requirements

2. PHPUnit Tests:

   • Unit tests in .../hvac-community-events/tests/unit/
   • Integration tests in .../hvac-community-events/tests/integration/
   • Execute on staging server via SSH
   • Test Environment Pattern with transaction management
   • Plugin verification and environment reset

3. Test Data System:

   • HVAC_Test_Data_Generator for consistent test data
   • HVAC_Test_User_Factory for persona management
   • Test environment setup/teardown scripts
   • Multi-role scenario testing support

Key Plugin Components

• Custom user roles (trainer, trainee)
• Event management integration with TEC
• Custom registration fields and user profiles
• Revenue tracking and reporting
• Certificate generation system
• Email communication features
• Zoho CRM API integration (Phase 2)
• HVAC Role Manager with hierarchical inheritance

Development Phases

• Phase 1: Core functionality (Completed)
• Phase 2: Zoho CRM API integration
• Phase 3: Enhanced event management features

Git Workflow

• Current branch: cloudways-dev
• Commits should be made after reasonable updates
• Developer: Ben Reed (ben@tealmaker.com)

System Patterns

Test Environment Pattern

• Database transactions for test isolation
• Automatic rollback after each test
• Plugin verification for TEC CE
• Clean state between tests

Test Data Generation Pattern

• Standardized data generation via HVAC_Test_Data_Generator
• Override support for custom scenarios
• Bulk generation capabilities
• Role-specific user creation

Role Management Pattern

• Hierarchical role inheritance with multiple parent support
• WordPress capability system with custom extensions
• Transaction-based role modifications
• Lightweight TEC capability integration

Important Notes

• Always deactivate/reactivate plugin when testing to ensure hooks fire
• Flush rewrite rules after plugin activation
• All development occurs on staging server, no local Docker environment
• Use absolute paths when executing commands
• Follow existing code conventions and patterns
• Update documentation after feature completion
• Test with multiple user personas to ensure proper functionality
• The project has migrated from Docker to Cloudways staging workflow
• Use transaction management for test isolation
• Verify plugin dependencies before running tests

Certificate Testing Guidelines

Certificate System Components

1. Certificate Generation

   • Generate certificates for checked-in attendees
   • Batch processing capabilities
   • PDF generation with customizable templates
   • Storage in wp_hvac_certificates table

2. Certificate Management/Reports

   • View generated certificates
   • Filter by event name and attendee details
   • Revoke certificates when needed
   • Resend certificates to attendees

Testing Certificate Functionality

1. Test Data Requirements

   • Events with varied attendee counts
   • Mix of checked-in and non-checked-in attendees
   • Diverse attendee names and emails for filter testing

2. Test Generation Process

   • Generate for all attendees
   • Generate for checked-in attendees only
   • Validate certificate metadata
   • Check PDF rendering

3. Test Filtering Capabilities

   • Filter by event name
   • Filter by attendee name
   • Filter by attendee email
   • Filter by certificate status
   • Combined filtering (event + attendee)

4. Test Data Scripts

   • Use test-certificate-filter.sh for comprehensive filter testing
   • Use create-test-data-with-checkins.sh to create test data
   • Use generate-test-certificates.sh to populate certificate database
   • Use verify-certificate-data.sh to validate data generation

For detailed documentation on certificate testing, see TESTING.md