# HVAC Plugin Configuration Guide

## Table of Contents
- [Overview](#overview)
- [System Architecture](#system-architecture)
- [Configuration Files](#configuration-files)
- [User Roles & Permissions](#user-roles--permissions)
- [URL Structure](#url-structure)
- [Theme Integration](#theme-integration)
- [Page Templates](#page-templates)
- [Navigation System](#navigation-system)
- [CSS & JavaScript Assets](#css--javascript-assets)
- [Database Structure](#database-structure)

## Overview

The HVAC Community Events plugin is a comprehensive event management system for HVAC trainers. It integrates with The Events Calendar (TEC) and provides custom functionality for trainer profiles, certificate generation, and event management.

## System Architecture

### Core Components

```
hvac-community-events/
├── includes/               # Core PHP classes
├── templates/             # Page templates
├── assets/                # CSS, JS, images
├── bin/                   # CLI scripts
├── scripts/               # Deployment scripts
├── tests/                 # Test suites
└── docs/                  # Documentation
```

### Key Classes

1. **HVAC_Plugin** - Main plugin class, handles initialization
2. **HVAC_Menu_System** - Navigation menu management
3. **HVAC_Astra_Integration** - Theme compatibility layer
4. **HVAC_Scripts_Styles** - Asset management
5. **HVAC_Shortcodes** - Shortcode implementations
6. **HVAC_Route_Manager** - URL routing and rewrites

## Configuration Files

### .env Configuration
```bash
# Staging Environment
UPSKILL_STAGING_IP=146.190.76.204
UPSKILL_STAGING_SSH_USER=roodev
UPSKILL_STAGING_PATH=/home/974670.cloudwaysapps.com/uberrxmprk/public_html
UPSKILL_STAGING_URL=https://upskill-staging.measurequick.com

# Production Environment (only when explicitly needed)
UPSKILL_PRODUCTION_IP=<production-ip>
UPSKILL_PRODUCTION_SSH_USER=<production-user>
UPSKILL_PRODUCTION_PATH=<production-path>
UPSKILL_PRODUCTION_URL=https://upskillhvac.com
```

### Plugin Constants (hvac-community-events.php)
```php
define('HVAC_PLUGIN_VERSION', '2.0.0');
define('HVAC_PLUGIN_PATH', plugin_dir_path(__FILE__));
define('HVAC_PLUGIN_URL', plugin_dir_url(__FILE__));
define('HVAC_PLUGIN_FILE', __FILE__);
```

## User Roles & Permissions

### Role Hierarchy
1. **hvac_master_trainer** - Full access to all features, aggregate reporting
2. **hvac_trainer** - Standard trainer access, manage own events
3. **event_trainer** - Legacy role (should be migrated to hvac_trainer)

### Capabilities
```php
// Master Trainer
- manage_all_events
- view_all_certificates
- access_master_dashboard
- manage_trainers

// Regular Trainer
- manage_own_events
- generate_certificates
- manage_profile
- manage_venues
- manage_organizers
```

### Important: Dual-Role Users
Users with both trainer and master trainer roles will ONLY see the master trainer navigation to prevent UI duplication.

## URL Structure

### Hierarchical URLs (implemented June 2025)
```
/trainer/
├── /dashboard/
├── /event/manage/
├── /certificate-reports/
├── /generate-certificates/
├── /profile/
├── /profile/edit/
├── /venue/list/
├── /venue/manage/
├── /organizer/list/
└── /organizer/manage/

/master-trainer/
├── /master-dashboard/
├── /events/
└── /reports/
```

### Legacy URL Redirects
All old URLs automatically redirect to new hierarchical structure:
- `/trainer-dashboard/` → `/trainer/dashboard/`
- `/trainer-profile/` → `/trainer/profile/`

## Theme Integration

### Astra Theme Compatibility
The plugin includes `HVAC_Astra_Integration` class that:
- Forces full-width layouts on all plugin pages
- Removes sidebars completely
- Adds custom body classes
- Overrides theme container widths

### Body Classes Added
```css
.hvac-plugin-page
.hvac-trainer-area
.hvac-astra-integrated
.ast-no-sidebar
.ast-full-width-layout
```

### Critical CSS Overrides
```css
/* Force full-width on HVAC pages */
.hvac-astra-integrated .ast-container {
    max-width: 100% !important;
    width: 100% !important;
}

/* Remove all sidebars */
.hvac-astra-integrated .widget-area,
.hvac-astra-integrated #secondary {
    display: none !important;
}
```

## Page Templates

### Template Files
All templates must include WordPress header/footer:
```php
<?php
// Template Name: Trainer Dashboard
define('HVAC_IN_PAGE_TEMPLATE', true);
get_header();
?>
<!-- Content -->
<?php
get_footer();
?>
```

### Template Assignment
Templates are automatically assigned during plugin activation. Manual assignment:
```php
update_post_meta($page_id, '_wp_page_template', 'templates/page-trainer-dashboard.php');
```

### Available Templates
- `page-trainer-dashboard.php`
- `page-trainer-profile.php`
- `page-certificate-reports.php`
- `page-generate-certificates.php`
- `page-manage-event.php`
- `page-master-dashboard.php`

## Navigation System

### Menu Registration
```php
// Rendered via HVAC_Menu_System::render_trainer_menu()
// Includes dropdown support and mobile hamburger menu
```

### Menu Structure
```php
[
    'Events' => [
        'Dashboard',
        'New Event'
    ],
    'Certificates' => [
        'Reports',
        'New Certificate'
    ],
    'Customize' => [
        'Personal Profile',
        'Training Organizers',
        'Training Venues'
    ]
]
```

### Navigation Rules
1. Check user capabilities before rendering
2. Dual-role users see only master trainer menu
3. Use `HVAC_NAV_RENDERED` constant to prevent duplicates

## CSS & JavaScript Assets

### Asset Loading
Managed by `HVAC_Scripts_Styles` class:
```php
// CSS files loaded conditionally on plugin pages
- hvac-dashboard.css
- hvac-menu-system.css
- hvac-layout.css
- hvac-profile.css

// JavaScript with proper dependencies
- hvac-dashboard.js (requires jQuery)
- hvac-menu-system.js
- hvac-profile.js
```

### Loading Conditions
```php
private function is_plugin_page() {
    // Checks URL patterns
    // Checks page templates
    // Checks HVAC_IN_PAGE_TEMPLATE constant
}
```

## Database Structure

### Custom Tables
None - plugin uses WordPress posts, user meta, and post meta

### Post Meta Keys
```php
// Event meta
'_EventStartDate'
'_EventEndDate'
'_EventVenueID'
'_EventOrganizerID'

// Page meta
'_wp_page_template'
'site-sidebar-layout'
'ast-site-sidebar-layout'
```

### User Meta Keys
```php
'hvac_trainer_photo'
'hvac_certifications'
'hvac_bio'
'hvac_website'
'hvac_location'
'hvac_training_formats'
'hvac_training_audience'
```

## Environment-Specific Settings

### Staging
- Debug logging enabled
- Cache clearing after deployment
- Test data seeding available

### Production
- Debug logging disabled
- Performance optimizations active
- Double confirmation required for deployment

## Integration Points

### The Events Calendar (TEC)
- Events created as 'tribe_events' post type
- Venues managed through TEC
- Organizers synced with TEC

### Zoho CRM
- OAuth integration for data sync
- Refresh token handling
- Production-only activation

### Certificate Generation
- TCPDF library for PDF creation
- Custom certificate templates
- Batch processing support

### Trainer Profile Sharing System
- QR code generation using QR Server API
- Shareable profile URLs with rewrite rules
- AJAX-powered sharing modals
- Professional profile cards with certification badges

## Profile Sharing Configuration

### QR Code Generation
The system uses QR Server API for generating QR codes:
```php
// API Endpoint
https://api.qrserver.com/v1/create-qr-code/

// Parameters
- size: QR code dimensions (default: 200x200)
- data: URL to encode
- ecc: Error correction level (L, M, Q, H)
```

### Share URL Structure
Profile sharing URLs follow this pattern:
```
https://example.com/find-a-trainer/profile/{profile_id}/
```

Important: URLs must include trailing slash for WordPress rewrite rules to work properly.

### Rewrite Rules
Custom rewrite rules handle direct profile access:
```php
add_rewrite_rule(
    '^find-a-trainer/profile/([0-9]+)/?$',
    'index.php?pagename=find-a-trainer&trainer_profile_id=$matches[1]',
    'top'
);
```

### AJAX Endpoints
Profile sharing uses these AJAX actions:
- `hvac_get_profile_share_data` - Retrieves profile data and QR code URL
- Requires nonce verification: `hvac_profile_sharing`

### CSS Classes for Styling
```css
.hvac-share-modal               # Modal overlay
.hvac-share-profile-card        # Profile card container
.hvac-share-avatar              # Profile image container
.hvac-share-qr                  # QR code container
.hvac-mq-badge-overlay          # Certification badge overlay
```

### JavaScript Localization
Profile sharing requires these localized variables:
```javascript
hvac_sharing.ajax_url           # WordPress AJAX URL
hvac_sharing.nonce             # Security nonce
hvac_sharing.strings.copied    # "Copied!" message
hvac_sharing.strings.copy_error # Copy error message
```