upskill-event-manager/docs/PLUGIN-ARCHITECTURE-REFACTORING.md

HVAC Plugin Architecture Refactoring Plan

Current Issues

1. Duplicate Functionality: HVAC_Plugin and HVAC_Community_Events have overlapping responsibilities
2. Multiple Initialization: Components are initialized in multiple places causing duplication
3. Mixed Concerns: Classes handle multiple unrelated responsibilities
4. Inconsistent Patterns: Some classes use singleton, others don't
5. Legacy Code: Backward compatibility code mixed with new features

Proposed Architecture

Phase 1: Create Dedicated Single-Responsibility Classes

1.1 HVAC_Shortcodes Class

• Purpose: Register and manage all plugin shortcodes
• Location: /includes/class-hvac-shortcodes.php
• Responsibilities:
  • Register all shortcodes in one place
  • Handle shortcode callbacks
  • Manage shortcode attributes and defaults

1.2 HVAC_Scripts_Styles Class

• Purpose: Manage all script and style enqueuing
• Location: /includes/class-hvac-scripts-styles.php
• Responsibilities:
  • Frontend script/style registration and enqueuing
  • Admin script/style registration and enqueuing
  • Script localization
  • Version management for cache busting

1.3 HVAC_Route_Manager Class

• Purpose: Handle all URL routing and redirects
• Location: /includes/class-hvac-route-manager.php
• Responsibilities:
  • Legacy URL redirects
  • Parent page redirects
  • Custom rewrite rules
  • Query var registration

Phase 2: Consolidate Authentication and Access Control

2.1 Enhance HVAC_Access_Control

• Move all authentication checks from HVAC_Community_Events
• Centralize page access rules
• Implement filter/action based access control

Phase 3: Refactor Main Plugin Classes

3.1 HVAC_Plugin (Main Plugin Controller)

• Keep:
  • Plugin activation/deactivation
  • Dependency loading
  • Component initialization (single point)
  • Hook registration
• Remove:
  • Direct script/style enqueuing (move to HVAC_Scripts_Styles)
  • Redirect handling (move to HVAC_Route_Manager)
  • AJAX handlers (move to respective feature classes)

3.2 HVAC_Community_Events (Deprecate)

• Phase 1: Remove all duplicate functionality
• Phase 2: Convert to compatibility layer
• Phase 3: Add deprecation notices
• Phase 4: Remove entirely in future version

Phase 4: Implement Consistent Patterns

4.1 Singleton Pattern

Apply to classes that should have single instances:

• HVAC_Plugin
• HVAC_Shortcodes
• HVAC_Scripts_Styles
• HVAC_Route_Manager
• HVAC_Access_Control

4.2 Interface-Based Design

Create interfaces for common patterns:

• HVAC_Component_Interface for initializable components
• HVAC_Ajax_Handler_Interface for AJAX handling classes
• HVAC_Admin_Page_Interface for admin page classes

Phase 5: Create Service Container

5.1 HVAC_Container Class

• Purpose: Manage dependency injection
• Features:
  • Lazy loading of components
  • Dependency resolution
  • Service registration

Implementation Order

1. Create new classes (non-breaking additions):

   • HVAC_Shortcodes
   • HVAC_Scripts_Styles
   • HVAC_Route_Manager

2. Move functionality (careful migration):

   • Migrate shortcodes from HVAC_Community_Events to HVAC_Shortcodes
   • Migrate scripts/styles to HVAC_Scripts_Styles
   • Migrate routing logic to HVAC_Route_Manager

3. Update initialization:

   • Update HVAC_Plugin to use new classes
   • Remove duplicate initializations

4. Deprecate legacy code:

   • Add deprecation notices to HVAC_Community_Events methods
   • Maintain backward compatibility temporarily

5. Clean up:

   • Remove deprecated code in future version
   • Update documentation
   • Update tests

Benefits

1. Clear Separation of Concerns: Each class has a single, well-defined purpose
2. Easier Maintenance: Changes to one feature won't affect others
3. Better Testing: Isolated components are easier to test
4. Reduced Duplication: Single source of truth for each functionality
5. Improved Performance: No duplicate initializations or hook registrations
6. Easier Onboarding: New developers can understand the architecture quickly

Backward Compatibility Strategy

1. Maintain existing hooks: Keep action/filter names unchanged
2. Proxy methods: Create proxy methods in deprecated classes
3. Gradual migration: Move functionality piece by piece
4. Version checks: Add version-based compatibility layers
5. Clear deprecation timeline: Document when features will be removed

Success Metrics

• No duplicate component initialization
• All functionality maintained
• No breaking changes for existing users
• Improved code organization
• Reduced file size and complexity
• Better performance metrics