# 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