upskill-event-manager/docs/TRAINER-ANNOUNCEMENTS-IMPLEMENTATION-PLAN.md

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