Technical Architecture Overview

​

Introduction

​

Technology Stack

​

Backend

• Language: PHP 7.4+
• Database Layer: PDO (PHP Data Objects) for secure database connections
• Session Management: PHP native sessions with custom authentication layer
• Password Hashing: WordPress Portable PHP Password Hashing Framework (Phpass)
• Integration: Optional WordPress authentication integration

​

Frontend

• HTML/CSS/JavaScript: Modern vanilla JavaScript with ES6+
• CSS Framework: Tailwind CSS (via Tailwind UI)
• Icons: Lucide Icons
• Fonts: Google Fonts (Inter)

​

Database

• RDBMS: MySQL 5.7+ / MariaDB 10.3+
• Character Set: utf8mb4 (full Unicode support)
• Engine: InnoDB (ACID compliance, foreign key support)

​

System Architecture

/workspace/source/
├── includes/          # Core system files
│   ├── auth.php      # Authentication and session management
│   ├── db.php        # Database connection and configuration
│   ├── config.php    # Application configuration
│   └── class-phpass.php # Password hashing library
├── assets/           # Frontend resources
│   ├── js/          # JavaScript libraries and custom scripts
│   └── css/         # Stylesheets
├── sql/             # Database schemas and migrations
├── *.php            # Application pages (login, dashboard, etc.)
└── dev/             # Development tools and logs

​

Core Components

​

1. Database Connection Layer

• PDO-based connections with prepared statements
• Environment-based configuration
• Comprehensive error handling and logging
• Graceful degradation with user-friendly error pages

// Database configuration via environment variables
$host = getenv('DB_HOST') ?: 'localhost';
$db = getenv('DB_NAME') ?: 'dilemas';
$user = getenv('DB_USER') ?: 'root';
$pass = getenv('DB_PASSWORD') ?: 'root';

​

2. Authentication System

• Uses WordPress core authentication functions
• Leverages wp_authenticate() for credential validation
• Supports WordPress roles and capabilities

• Direct PDO queries against de_users table
• Multi-method password verification (Bcrypt, WordPress Phpass)
• Role-based access control via user metadata

​

3. Session Management

$_SESSION['user_id']      // WordPress/Database user ID
$_SESSION['user_login']   // Username
$_SESSION['display_name'] // Full name for display
$_SESSION['role']        // User role (administrator, editor, subscriber)
$_SESSION['logged_in']   // Authentication flag

​

4. Rate Limiting

• Max Attempts: 5 failed login attempts
• Lockout Window: 15 minutes (900 seconds)
• Storage: File-based temporary storage in system temp directory
• Scope: IP address-based limiting

​

Multi-Tenant Architecture

• Each client has isolated areas, users, and games
• Users belong to a specific client and area
• Games are assigned to specific clients
• Analytics and reports are client-scoped

​

Data Flow

​

User Participation Flow

1. Registration/Invitation: Admin creates user accounts linked to client and area
2. Authentication: User logs in via credential-based or link-based access
3. Game Assignment: User is assigned one or more ethical dilemma scenarios
4. Participation: User answers questions, responses are tracked
5. Analytics: System generates participation metrics and performance data
6. Certification: Upon completion, certificates are generated and delivered

​

Administrative Flow

1. Client Onboarding: Create new client organization
2. Area Configuration: Define departments/areas within client
3. User Management: Import or manually create user accounts
4. Game Setup: Configure dilemma scenarios and questions
5. Monitoring: Track participation via dashboard and analytics
6. Reporting: Generate performance reports and certificates

​

Security Features

​

Password Security

• Hashing: Phpass (WordPress Portable) with 8 iteration rounds
• Fallback Support: Bcrypt compatibility for modern PHP installations
• Password Reset: Secure token-based recovery with time-limited keys

​

Database Security

• Prepared Statements: All queries use PDO prepared statements
• SQL Injection Protection: Parameterized queries prevent injection attacks
• Error Suppression: Production environments hide SQL error details

​

Session Security

• Session Hijacking Protection: IP-based rate limiting
• Secure Token Generation: Cryptographically secure random bytes for reset tokens
• Session Timeout: Automatic logout after inactivity

​

Input Validation

• XSS Prevention: htmlspecialchars() on all user-generated output
• CSRF Protection: Form token validation (implementation-specific)

​

Asynchronous Processing

• Email Reminders: cron_email_reminders.php sends participation reminders
• Weekly Reports: weekly_report.php generates and distributes analytics
• Certificate Generation: Automated diploma creation for completions

​

Logging and Debugging

​

Authentication Logs

• Location: auth_debug.log (root directory)
• Content: Login attempts, authentication method used, role detection
• Format: Timestamped entries with detailed context

​

Database Error Logs

• Location: dev/debug/error.log
• Content: Connection failures, query errors
• Security: Sanitized to prevent credential exposure

​

Performance Considerations

​

Database Optimization

• Indexes: Primary keys on all ID columns, foreign key indexes
• Charset: utf8mb4 with unicode collation for emoji support
• Connection Pooling: PDO persistent connections (configurable)

​

Frontend Performance

• Asset Versioning: Query string cache busting based on file modification time
• Minimal Dependencies: Core libraries loaded from local assets
• Lazy Loading: Icons rendered via Lucide client-side library

​

Deployment Architecture

• PHP 7.4 or higher
• MySQL 5.7 or MariaDB 10.3+
• Apache with mod_rewrite or Nginx with PHP-FPM
• 256MB PHP memory limit
• SMTP server for email delivery (optional WordPress wp_mail integration)

DB_HOST=localhost
DB_NAME=dilemas
DB_USER=dilemas_user
DB_PASSWORD=secure_password

​

Integration Points

​

WordPress Integration (Optional)

• User authentication delegates to wp_authenticate()
• Password resets use get_password_reset_key()
• Email delivery uses wp_mail()
• User roles mapped from WordPress capabilities

​

Standalone Operation

• Authenticates against de_users table
• Uses PHP mail() function for email delivery
• Manages roles via de_usermeta table
• Self-contained user management

​

Scalability Considerations

• Horizontal Scaling: Stateless design allows load balancing across multiple PHP servers
• Database Scaling: Foreign key relationships support read replicas
• Caching Layer: Compatible with Redis/Memcached for session storage
• CDN Integration: Static assets can be served from CDN

​

Next Steps

• Database Schema - Detailed table structures and relationships
• Authentication & Sessions - Deep dive into security implementation