upskill-event-manager/memory-bank/decisionLog.md

Decision Log

This file records architectural and implementation decisions using a list format. 2025-03-26 11:11:00 - Updated with development environment workflow decisions

Core Architectural Decisions

Development Environment Configuration

• Decision: Implement Docker-based development environment with PHP-FPM
• Rationale: Better performance, control, and similarity to production
• Implementation Details:
  • WordPress with PHP 8.1-FPM
  • Nginx as web server
  • MariaDB for database
  • Custom PHP-FPM configuration
  • Development-specific WordPress settings

Development Environment Workflow

• Decision: Implement backup-based workflow for development environment setup
• Rationale: More reliable, faster setup, offline support, and consistent environments
• Implementation Details:
  • Create backups from production using sync-production.sh
  • Set up environment from backups using setup-from-backup.sh
  • Standardized script naming and organization
  • Comprehensive documentation and migration guide
  • Improved error handling and verification

WordPress Configuration Strategy

• Decision: Use environment variables and wp-config.php overrides
• Rationale: Maintain security and flexibility across environments
• Implementation Details:
  • Environment-based configuration
  • Debug mode in development
  • Custom site URL handling
  • SSL configuration options
  • Security settings management

Database Management

• Decision: Use MariaDB with custom configuration
• Rationale: Better performance and compatibility
• Implementation Details:
  • Custom character set and collation
  • Optimized buffer settings
  • Development-specific permissions
  • Backup and restore capabilities
  • Data synchronization tools

Version Control Strategy

• Decision: Implement Git-based version control with GitHub hosting
• Rationale: Enable collaborative development, code review, and version tracking
• Implementation Details:
  • Git repository with main branch
  • GitHub remote for collaboration
  • .gitignore to exclude environment-specific files
  • Structured commit messages
  • Clean repository history

Registration and Authentication Architecture

• Decision: Implement custom registration and authentication system
• Rationale: Need fine-grained control over user registration process and role management
• Implementation Details:
  • Custom database table for trainer profiles
  • Client and server-side validation
  • Automated venue creation integration
  • Email notification system
  • Role-based access control
  • Security measures following WordPress best practices

SSL Configuration for Development

• Decision: Disable SSL requirement in development
• Rationale: Simplify local development while maintaining production security
• Implementation Details:
  • Configurable SSL settings
  • Environment-specific SSL handling
  • Production-ready SSL configuration
  • Secure cookie handling
  • HTTPS redirection management

Custom Role Architecture

• Decision: Implement hvac_trainer custom WordPress role
• Rationale: Provide specific capabilities while restricting administrative access
• Implementation Details:
  • Role name: hvac_trainer
  • Custom capabilities for HVAC-specific features
  • Integration with The Events Calendar capabilities
  • Automatic role management through plugin lifecycle
  • Strict security boundaries

Integration-First Development Approach

• Decision: Maximize use of existing WordPress and The Events Calendar functionality
• Rationale: Leverage proven solutions, reduce custom code, ensure maintainability
• Implementation Details:
  • Use WordPress core features whenever possible
  • Extend The Events Calendar functionality rather than rebuild
  • Custom development only when necessary
  • Maintain plugin upgrade compatibility

2025-03-26 11:11:00 - Added development environment workflow decisions 2025-03-26 11:40:00 - Architectural Decision: Plugin Structure

• Decision: Created custom plugin rather than modifying existing registration plugins
• Rationale: Need complete control over form fields and validation specific to HVAC trainers
• Implementation Details:
  • Standalone WordPress plugin structure
  • Custom form handler class

2025-03-27 13:54:00 - Testing Environment Architecture

• Decision: Implement WordPress unit testing framework within Docker container
• Rationale: More reliable, consistent testing environment that matches production configuration
• Implementation Details:
  • Install testing dependencies directly in WordPress container
  • Configure database access from container to MariaDB
  • Share test files via Docker volumes
  • Standardize test execution process with helper scripts
  • Allow for both local and CI/CD testing with same configuration

2025-03-28 05:32:00 - Test Configuration Architecture

• Decision: Configure WordPress test environment using wp-tests-config.php in Docker container
• Rationale: Ensure consistent test environment across all development machines while maintaining Docker isolation
• Implementation Details:
  • Use environment-specific database settings (host: 'db', proper credentials)
  • Configure correct WordPress core paths for Docker container (/var/www/html/)
  • Standardize test framework file locations
  • Maintain separation between development and test databases
  • Use Docker environment variables for sensitive configuration

[2025-03-28 16:24:00] - Test Environment Configuration Decisions

• Decision: Use Composer (wp-phpunit/wp-phpunit) for PHPUnit test framework installation, removing manual/SVN steps from Dockerfile and documentation.

• Rationale: Aligns with standard PHP practices, simplifies Dockerfile, resolves SVN dependency issues.

• Decision: Configure PHPUnit environment using a combination of files:

  • phpunit.xml.dist: Defines test suites only (no PHP constants).
  • wp-tests-config.php (host wordpress-dev/): Defines test DB credentials (hardcoded root password) and ABSPATH. Mounted via volume.
  • tests/bootstrap.php (host wordpress-dev/): Defines ABSPATH early, defines WP_TESTS_CONFIG_FILE_PATH, defines WP_TESTS_RUNNING, finds vendor test library, loads plugin, requires main test bootstrap.
  • wp-config.php (host wordpress-dev/wordpress/): Wraps main DB constant definitions in if (!defined('WP_TESTS_RUNNING')).

• Rationale: Resolves constant redefinition errors, ABSPATH errors, and database connection failures during PHPUnit bootstrap by ensuring correct loading order and configuration precedence.

• Decision: Install WP-CLI via direct volume mount (./bin/wp-cli.phar:/usr/local/bin/wp) in docker-compose.yml instead of Dockerfile RUN commands.

• Rationale: Bypasses persistent failures during Docker image build process related to curl/chmod/mv steps.

• Decision: Increase PHP memory_limit to 512M via mounted php.ini/custom.ini.

• Rationale: Resolves fatal memory exhaustion errors encountered when running WP-CLI and potentially PHPUnit.

• Decision: Modify bin/run-tests.sh to exit 1 on unit/integration test failure.

• Rationale: Prevents unnecessary execution of E2E tests when earlier, fundamental tests fail.

• Decision: Consolidate docs/test-environment-plan.md and wordpress-dev/testing.md into wordpress-dev/testing.md.

• Rationale: Centralizes testing information, removes redundancy, incorporates fixes identified during debugging.

[2025-03-28 16:47:00] - Automatic Page Creation

• Decision: Implement automatic creation of required plugin pages (Login, Registration, Dashboard) upon plugin activation.
• Rationale: Ensures consistent environment setup, simplifies user experience, and resolves E2E test failures caused by missing pages. Avoids manual setup steps.
• Implementation Details:
  • Use register_activation_hook in the main plugin file.
  • Callback function checks for existing pages by slug using get_page_by_path.
  • If page doesn't exist, create it using wp_insert_post with predefined title, slug, and content (using Gutenberg block format for shortcodes).
  • Refer to docs/automatic-page-creation-plan.md for full details.

• Theme-compatible CSS styling
• Integration with The Events Calendar planned