# Trainer Announcements Implementation Plan

## Architecture Decision
Based on unanimous consensus from architectural analysis, the system will use **modular architecture with specialized classes** following the Single Responsibility Principle (SRP).

## Class Structure

### Core Classes
1. **HVAC_Announcements_CPT** (`includes/class-hvac-announcements-cpt.php`)
   - Register custom post type `hvac_announcement`
   - Register taxonomies (categories, tags)
   - Define post type supports and capabilities

2. **HVAC_Announcements_Manager** (`includes/class-hvac-announcements-manager.php`)
   - Core orchestration and business logic
   - Singleton pattern implementation
   - Hook registration and initialization

3. **HVAC_Announcements_Ajax** (`includes/class-hvac-announcements-ajax.php`)
   - AJAX handlers for CRUD operations
   - Modal data processing
   - Nonce verification and security

4. **HVAC_Announcements_Email** (`includes/class-hvac-announcements-email.php`)
   - Email notification system
   - HTML template generation
   - Batch processing for large recipient lists

5. **HVAC_Announcements_Display** (`includes/class-hvac-announcements-display.php`)
   - Frontend display formatting
   - Shortcode handlers
   - Template rendering

6. **HVAC_Announcements_Permissions** (`includes/class-hvac-announcements-permissions.php`)
   - Role-based access control
   - Capability management
   - User permission checks

## Implementation Phases

### Phase 1: Core Infrastructure (Day 1)
- [ ] Create `HVAC_Announcements_CPT` class
  - Register `hvac_announcement` post type
  - Set up taxonomies
  - Configure capabilities
- [ ] Create `HVAC_Announcements_Permissions` class
  - Add capabilities to roles on activation
  - Implement permission check methods
- [ ] Create `HVAC_Announcements_Manager` class
  - Singleton implementation
  - Initialize all components
  - Register hooks

### Phase 2: Master Trainer Interface (Day 1-2)
- [ ] Create master announcements page template
  - Path: `templates/page-master-announcements.php`
  - Include navigation and breadcrumbs
  - Add announcements table structure
- [ ] Implement `HVAC_Announcements_Ajax` class
  - `hvac_get_announcements` endpoint
  - `hvac_create_announcement` endpoint
  - `hvac_update_announcement` endpoint
  - `hvac_delete_announcement` endpoint
- [ ] Build modal popup system
  - Add/Edit announcement forms
  - TinyMCE integration
  - Media uploader for featured image
- [ ] Create JavaScript for modal interactions
  - File: `assets/js/hvac-announcements-admin.js`
- [ ] Style the interface
  - File: `assets/css/hvac-announcements-admin.css`

### Phase 3: Trainer Resources Page (Day 2)
- [ ] Create trainer resources page template
  - Path: `templates/page-trainer-resources.php`
  - Include navigation and breadcrumbs
- [ ] Add Gutenberg blocks content
  - UAGB Post Timeline for announcements
  - Google Drive iframe embed
- [ ] Implement `HVAC_Announcements_Display` class
  - Format announcement output
  - Handle timeline display
- [ ] Ensure proper access control
  - Verify trainer/master trainer roles

### Phase 4: Navigation & Integration (Day 2)
- [ ] Update `HVAC_Menu_System` class
  - Add "Announcements" to master trainer menu
  - Add "Resources" to trainer menu
- [ ] Update breadcrumb configuration
  - Add new pages to breadcrumb trail
- [ ] Ensure Astra theme integration
  - Force full-width layout
  - Remove sidebar

### Phase 5: Email System (Day 3)
- [ ] Implement `HVAC_Announcements_Email` class
  - Hook into post status transitions
  - Build recipient list (active trainers only)
  - Generate HTML email from template
- [ ] Create email template
  - Path: `templates/email/announcement-notification.php`
  - Include announcement content
  - Add branding and footer
- [ ] Implement batch processing
  - Use WP-Cron for asynchronous sending
  - Add retry mechanism for failures
- [ ] Add email logging
  - Track sent emails in post meta
  - Log failures for debugging

### Phase 6: Testing & Quality Assurance (Day 3-4)
- [ ] Write unit tests
  - Test post type registration
  - Test capability assignments
  - Test AJAX endpoints
  - Test email queue
- [ ] Create Playwright E2E tests
  - Test announcement creation workflow
  - Test edit/delete operations
  - Test access control
  - Test email notifications
  - Test navigation updates
- [ ] Manual testing checklist
  - Verify all user roles
  - Test on mobile devices
  - Check email rendering
- [ ] Code review with Zen
  - Security audit
  - Performance review
  - Best practices check

### Phase 7: Deployment (Day 4)
- [ ] Pre-deployment checks
  - Run `bin/pre-deployment-check.sh`
  - Verify all tests pass
- [ ] Deploy to staging
  - Use `scripts/deploy.sh staging`
  - Test on staging environment
- [ ] Create test data
  - Sample announcements
  - Test email sends
- [ ] Document any issues
- [ ] Prepare for production

## File Structure

```
hvac-community-events/
├── includes/
│   ├── class-hvac-announcements-cpt.php
│   ├── class-hvac-announcements-manager.php
│   ├── class-hvac-announcements-ajax.php
│   ├── class-hvac-announcements-email.php
│   ├── class-hvac-announcements-display.php
│   └── class-hvac-announcements-permissions.php
├── templates/
│   ├── page-master-announcements.php
│   ├── page-trainer-resources.php
│   └── email/
│       └── announcement-notification.php
├── assets/
│   ├── js/
│   │   └── hvac-announcements-admin.js
│   └── css/
│       └── hvac-announcements-admin.css
└── tests/
    ├── unit/
    │   └── test-announcements.php
    └── e2e/
        └── test-announcements-workflow.js
```

## Success Criteria

1. **Functionality**
   - Master trainers can create, edit, delete announcements
   - All trainers can view announcements
   - Email notifications sent to active trainers
   - Google Drive embedded successfully

2. **User Experience**
   - Modal popups work smoothly
   - Navigation items appear correctly
   - Pages load within 2 seconds
   - Mobile responsive design

3. **Security**
   - Proper capability checks enforced
   - All inputs sanitized
   - All outputs escaped
   - Nonces verified on all forms

4. **Code Quality**
   - Follows WordPress coding standards
   - Consistent with existing plugin architecture
   - Comprehensive test coverage
   - Well-documented code

5. **Performance**
   - Efficient database queries
   - Proper caching implemented
   - Assets loaded conditionally
   - Email batch processing works

## Risk Mitigation

1. **Email Delivery Issues**
   - Implement retry mechanism
   - Add logging for debugging
   - Consider email service integration

2. **Permission Conflicts**
   - Thorough testing of all role combinations
   - Clear capability definitions
   - Fallback permission checks

3. **Theme Compatibility**
   - Test with Astra theme
   - Ensure proper template hierarchy
   - Add compatibility checks

4. **Performance Concerns**
   - Implement pagination
   - Use transient caching
   - Optimize database queries

## Timeline

- **Day 1**: Core infrastructure and master trainer interface (50%)
- **Day 2**: Complete interface, trainer resources, navigation
- **Day 3**: Email system and testing
- **Day 4**: Final testing, code review, and deployment

## Dependencies

- WordPress 5.0+ (Gutenberg support)
- Ultimate Addons for Gutenberg (UAGB)
- Astra theme
- Existing HVAC plugin infrastructure

## Notes

- All classes follow singleton pattern
- Use existing HVAC plugin patterns for consistency
- Prioritize security and performance
- Maintain backward compatibility
- Document all public methods