upskill-event-manager/docs/ARCHITECTURE.md

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

CSS Architecture

Stylesheet Organization

• hvac-dashboard.css - Base dashboard styles, stat cards, tables
• hvac-dashboard-enhanced.css - Advanced dashboard features
• hvac-event-manage.css - Event creation/editing form styles
• hvac-layout.css - Layout containers and responsive grids
• hvac-common.css - Shared components and utilities
• hvac-page-templates.css - Page-specific template styles

CSS Methodology

• Scoped Selectors: All styles scoped to prevent theme conflicts
  • Example: .hvac-event-manage-wrapper .tribe-section
• CSS Variables: Used for consistent theming
  • --hvac-primary, --hvac-spacing-*, --hvac-radius-*
• Mobile-First: Responsive breakpoints at 768px
• BEM-like Naming: Component-based class naming

Theme Compatibility

• Styles use high specificity to override theme defaults
• Container max-width enforced at 1200px
• Consistent 20px padding on all pages
• Theme layout constraints overridden where necessary

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