# HVAC Community Events - Plugin Architecture

## Overview

The HVAC Community Events plugin follows a modular, single-responsibility architecture designed for maintainability and extensibility.

## Core Architecture Components

### 1. HVAC_Plugin (Main Controller)
- **Location**: `/includes/class-hvac-plugin.php`
- **Purpose**: Main plugin initialization and coordination
- **Responsibilities**:
  - Plugin activation/deactivation
  - Loading dependencies
  - Initializing core components
  - Hook registration

### 2. HVAC_Shortcodes
- **Location**: `/includes/class-hvac-shortcodes.php`
- **Purpose**: Centralized shortcode management
- **Responsibilities**:
  - Register all plugin shortcodes
  - Handle shortcode callbacks
  - Manage shortcode attributes
- **Key Shortcodes**:
  - `[hvac_dashboard]` - Trainer dashboard
  - `[hvac_master_dashboard]` - Master trainer dashboard
  - `[hvac_trainer_registration]` - Registration form
  - `[hvac_community_login]` - Login form
  - `[hvac_manage_event]` - Event management
  - `[hvac_certificate_reports]` - Certificate reports

### 3. HVAC_Scripts_Styles
- **Location**: `/includes/class-hvac-scripts-styles.php`
- **Purpose**: Asset management
- **Responsibilities**:
  - Frontend script/style enqueuing
  - Admin script/style enqueuing
  - Script localization
  - Cache busting

### 4. HVAC_Route_Manager
- **Location**: `/includes/class-hvac-route-manager.php`
- **Purpose**: URL routing and redirects
- **Responsibilities**:
  - Legacy URL redirects
  - Parent page redirects
  - Custom rewrite rules
  - Query var registration

### 5. HVAC_Template_Loader
- **Location**: `/includes/class-hvac-template-loader.php`
- **Purpose**: Template handling
- **Responsibilities**:
  - Load custom templates
  - Template hierarchy
  - Theme compatibility

### 6. HVAC_Page_Manager
- **Location**: `/includes/class-hvac-page-manager.php`
- **Purpose**: WordPress page management
- **Responsibilities**:
  - Create plugin pages
  - Manage page hierarchy
  - Set page templates

## Feature Components

### Authentication & Access Control
- **HVAC_Access_Control**: Page access restrictions
- **HVAC_Roles**: User role management
- **HVAC_Trainer_Status**: Trainer approval status

### Event Management
- **HVAC_Manage_Event**: Event creation/editing
- **HVAC_Event_Summary**: Event details display
- **Event_Form_Handler**: Form processing

### Dashboards
- **HVAC_Dashboard**: Trainer dashboard
- **HVAC_Master_Dashboard**: Master trainer dashboard
- **HVAC_Dashboard_Data**: Dashboard data processing

### Certificate System
- **HVAC_Certificate_Manager**: Certificate generation
- **HVAC_Certificate_Security**: Security measures
- **HVAC_Certificate_URL_Handler**: URL processing

### Communication
- **HVAC_Communication_Templates**: Email templates
- **HVAC_Communication_Scheduler**: Automated emails

## Design Patterns

### Singleton Pattern
Used for classes that should have only one instance:
- HVAC_Plugin
- HVAC_Shortcodes
- HVAC_Scripts_Styles
- HVAC_Route_Manager
- HVAC_Help_System
- HVAC_Certificate_Security

### Hook-Based Architecture
WordPress actions and filters are used extensively:
- `init` - Component initialization
- `wp_enqueue_scripts` - Frontend assets
- `admin_enqueue_scripts` - Admin assets
- `template_redirect` - Access control

## File Structure

```
hvac-community-events/
├── hvac-community-events.php    # Main plugin file
├── includes/
│   ├── class-hvac-plugin.php    # Main controller
│   ├── class-hvac-shortcodes.php # Shortcode manager
│   ├── class-hvac-scripts-styles.php # Asset manager
│   ├── class-hvac-route-manager.php # URL routing
│   ├── class-hvac-template-loader.php # Templates
│   ├── class-hvac-page-manager.php # Page creation
│   ├── class-hvac-access-control.php # Access control
│   ├── admin/                    # Admin classes
│   ├── certificates/             # Certificate system
│   └── communication/            # Email system
├── templates/                    # Template files
├── assets/
│   ├── css/                     # Stylesheets
│   └── js/                      # JavaScript
└── docs/                        # Documentation
```

## Initialization Flow

1. `hvac-community-events.php` loads
2. `HVAC_Plugin::instance()` singleton created
3. Core components initialized:
   - HVAC_Shortcodes
   - HVAC_Scripts_Styles
   - HVAC_Route_Manager
   - HVAC_Template_Loader
4. Feature components loaded
5. Hooks registered
6. Ready for requests

## Database Tables

- `{prefix}_hvac_certificates` - Certificate records
- `{prefix}_hvac_communication_schedules` - Email schedules
- `{prefix}_hvac_google_sheets_auth` - Google Sheets tokens

## Key URLs

### Trainer Pages
- `/trainer/dashboard/` - Main dashboard
- `/trainer/registration/` - Registration form
- `/trainer/event/manage/` - Create/edit events
- `/trainer/certificate-reports/` - View certificates

### Master Trainer Pages
- `/master-trainer/dashboard/` - Master dashboard
- `/master-trainer/google-sheets/` - Google Sheets integration

### Public Pages
- `/training-login/` - Login page
- `/trainer/registration/` - Public registration

## Security

- Capability-based access control
- Nonce verification for forms
- Prepared SQL statements
- Escaped output
- Sanitized input

## Performance Optimizations

- Singleton patterns prevent duplicate initialization
- Assets loaded only on relevant pages
- Database queries optimized
- Caching implemented where appropriate

## Future Improvements

1. Implement PSR-4 autoloading
2. Add unit test coverage
3. Implement dependency injection container
4. Add REST API endpoints
5. Enhance caching strategies