docs: consolidate documentation into organized structure

- Move 12 markdown files from root to docs/ subdirectories
- Organize documentation by category:
  • docs/troubleshooting/ (1 file)  - Technical troubleshooting guides
  • docs/deployment/      (4 files) - Deployment and security documentation
  • docs/guides/          (3 files) - Feature-specific guides
  • docs/planning/        (4 files) - Planning and improvement proposals

Root directory cleanup:
- Reduced from 16 to 4 markdown files in root
- Only essential project files remain:
  • CLAUDE.md (AI instructions)
  • README.md (Main project readme)
  • CLEANUP_PLAN.md (Current cleanup plan)
  • SRC_STRUCTURE_IMPROVEMENTS.md (Structure improvements)

This improves:
✅ Documentation discoverability
✅ Logical organization by purpose
✅ Clean root directory
✅ Better maintainability

docs/deployment/DEPLOYMENT.md

@@ -0,0 +1,73 @@
+# 🚀 Production Deployment Guide
+
+## Schneller Deployment-Workflow
+
+### 1. Environment Setup (KRITISCH)
+```bash
+# Kopiere .env Template
+cp .env.production .env
+
+# Setze ALLE CHANGE_ME Werte:
+nano .env
+```
+
+**WICHTIG:** Folgende Werte MÜSSEN gesetzt werden:
+- `DB_PASSWORD` - Starkes Datenbankpasswort
+- `SHOPIFY_WEBHOOK_SECRET` - Nur wenn Shopify verwendet wird
+- `RAPIDMAIL_USERNAME/PASSWORD` - Nur wenn RapidMail verwendet wird
+
+### 2. Database Setup
+```bash
+# 1. Datenbank erstellen
+mysql -u root -p
+CREATE DATABASE production_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'production_user'@'localhost' IDENTIFIED BY 'DEIN_PASSWORT';
+GRANT ALL PRIVILEGES ON production_db.* TO 'production_user'@'localhost';
+FLUSH PRIVILEGES;
+EXIT;
+
+# 2. Migration ausführen
+mysql -u production_user -p production_db < migrations/2024_01_01_create_meta_entries_table.sql
+```
+
+### 3. Assets Build (falls Frontend verwendet)
+```bash
+npm install
+npm run build
+```
+
+### 4. Basic Health Check
+```bash
+# Server starten und testen
+php -S localhost:8000 -t public/
+curl http://localhost:8000/
+```
+
+## Sicherheits-Checklist ✅
+
+- [x] Keine hardcoded Secrets im Code
+- [x] Starke Datenbankpasswörter
+- [x] Production .env Template erstellt
+- [x] Environment-basierte Konfiguration
+
+## Next Steps (Optional)
+
+1. **SSL Setup** - Let's Encrypt oder eigene Zertifikate
+2. **Webserver Config** - nginx/Apache Konfiguration
+3. **Process Manager** - PM2, systemd oder supervisor
+4. **Monitoring** - Log-Aggregation und Error-Tracking
+5. **Backup Strategy** - Automatische DB-Backups
+
+## Rollback Strategy
+
+Bei Problemen:
+```bash
+# 1. Alte Version aktivieren
+git checkout previous-version
+
+# 2. Assets neu bauen (falls nötig)
+npm run build
+
+# 3. Cache leeren
+# (abhängig von Setup)
+```

docs/deployment/DEPLOYMENT_RESTRUCTURE.md

@@ -0,0 +1,96 @@
+# Deployment System Restructuring Complete
+
+## Summary
+
+The deployment system has been successfully restructured from multiple scattered configurations into a modern, organized hybrid deployment system.
+
+## What Was Done
+
+### 1. Backup Creation
+Created `.deployment-backup/` directory containing all old deployment files:
+- `ansible/` - Multiple Ansible configurations (netcup-simple-deploy, nginx-cdn-germany, wireguard-server)  
+- `x_ansible/` - Alternative Ansible setup
+- `ssl/` - SSL certificates for local development
+- `bin/` - Deployment utility scripts
+- `BACKUP_SUMMARY.md` - Detailed backup documentation
+
+### 2. New Structure Creation
+Created modern `deployment/` directory with four main components:
+
+**Infrastructure** (`deployment/infrastructure/`)
+- Ansible playbooks for server setup and management
+- Environment-specific inventories  
+- Reusable roles for common tasks
+- Configuration management via group_vars
+
+**Applications** (`deployment/applications/`)
+- Docker Compose configurations per environment
+- Production, staging, and development setups
+- Service orchestration and health monitoring
+- Environment-specific optimizations
+
+**Scripts** (`deployment/scripts/`)
+- Automated deployment orchestration
+- Setup, rollback, and utility scripts
+- Health checking and monitoring tools
+- Integration with infrastructure and applications
+
+**Configs** (`deployment/configs/`)
+- Configuration templates for all services
+- Nginx, PHP, MySQL, and SSL configurations
+- Environment-specific template variables
+- Monitoring and logging configurations
+
+## Key Improvements
+
+✅ **Separation of Concerns**: Clear distinction between infrastructure and application deployment  
+✅ **Environment Management**: Dedicated configurations for production, staging, development  
+✅ **Docker Integration**: Full containerization with Docker Compose  
+✅ **Automation**: Streamlined deployment workflows  
+✅ **Configuration Management**: Centralized template system  
+✅ **Documentation**: Comprehensive README files for each component  
+
+## Next Steps
+
+1. **Infrastructure Setup** (`deployment/infrastructure/`)
+   - Create Ansible inventories for environments
+   - Develop server setup playbooks
+   - Configure security and Docker roles
+
+2. **Application Configuration** (`deployment/applications/`)
+   - Create environment-specific Docker Compose files
+   - Configure service networking and volumes
+   - Set up health checks and monitoring
+
+3. **Script Development** (`deployment/scripts/`)
+   - Implement main deployment orchestration script
+   - Create setup and rollback automation
+   - Develop health monitoring tools
+
+4. **Configuration Templates** (`deployment/configs/`)
+   - Create Nginx configuration templates
+   - Set up SSL certificate management  
+   - Configure environment file templates
+
+## Migration Benefits
+
+- **Maintainability**: Organized, documented structure
+- **Scalability**: Easy to add new environments or services  
+- **Reliability**: Automated testing and rollback capabilities
+- **Security**: Modern security practices and SSL management
+- **Consistency**: Standardized deployment across environments
+
+## Rollback Option
+
+If needed, the old system can be quickly restored by moving files back from `.deployment-backup/` to their original locations. See `BACKUP_SUMMARY.md` for detailed instructions.
+
+## Framework Integration
+
+The new deployment system is specifically designed for the Custom PHP Framework with:
+- HTTPS-first configuration (framework requirement)
+- Docker-based architecture (current setup)
+- Production server targeting (94.16.110.151 with deploy user)
+- SSL certificate automation for framework's HTTPS requirement
+- Health check integration with framework's built-in endpoints
+
+This modern deployment system provides a solid foundation for reliable, automated deployment of the Custom PHP Framework across all environments.

docs/deployment/PRODUCTION-SECURITY-UPDATES.md

@@ -0,0 +1,134 @@
+# Production Security Configuration Updates
+
+## Overview
+
+Updated the production security configuration for michaelschiemer.de using a SINGLE docker-compose.yml approach with environment-based configuration.
+
+## Critical Security Fixes Applied
+
+### 1. Performance Debug Information
+- **Issue**: Performance debug information was visible on production
+- **Fix**: Updated `PerformanceServiceInitializer.php` to strictly check both `APP_ENV=production` AND `APP_DEBUG=false`
+- **Result**: Debug performance tracking disabled in production (`ANALYTICS_TRACK_PERFORMANCE=false` in `.env.production`)
+
+### 2. Session Debug Data Exposure
+- **Issue**: Session debug data was exposed in production
+- **Fix**: Performance service now disables detailed reports in production
+- **Result**: Session info and debug data hidden when `APP_ENV=production`
+
+### 3. Admin Routes Security
+- **Issue**: Admin routes were not properly secured
+- **Fix**: Added `ProductionSecurityMiddleware` to middleware stack (priority #2 - early execution)
+- **Result**: Admin/debug routes return 404 in production, IP-restricted routes require whitelist
+
+## Files Updated
+
+### 1. `/src/Framework/Http/MiddlewareManager.php`
+- Added `ProductionSecurityMiddleware` to middleware stack (position #2 for early execution)
+- Updated middleware numbering to maintain proper order
+
+### 2. `/deploy.sh`
+- Changed deployment to copy `.env.production` to `.env` instead of using `.env.example`
+- Added production configuration validation step
+- Added security endpoint testing during deployment
+
+### 3. `/.env.production`
+- Added `ADMIN_ALLOWED_IPS=127.0.0.1,::1` for IP whitelisting
+- Set `ANALYTICS_TRACK_PERFORMANCE=false` to disable debug performance tracking
+- Confirmed `XDEBUG_MODE=off` for production
+
+### 4. Created `/test-security.sh`
+- Comprehensive security testing script for local validation
+- Tests blocked routes, IP-restricted routes, and environment configuration
+
+## Security Middleware Configuration
+
+### ProductionSecurityMiddleware Behavior
+
+**Blocked Routes in Production** (returns 404):
+- `/admin/discovery`
+- `/admin/routes` 
+- `/admin/performance`
+- `/admin/environment`
+- `/debug`
+- `/performance`
+- `/api/debug`
+
+**IP-Restricted Routes in Production** (requires whitelist):
+- `/admin`
+- `/analytics`
+- `/health`
+- `/metrics`
+
+**Allowed IPs** (configurable via `ADMIN_ALLOWED_IPS` environment variable):
+- `127.0.0.1` (localhost IPv4)
+- `::1` (localhost IPv6)
+- Additional IPs can be added as comma-separated values
+
+## Environment-Based Configuration
+
+### Single docker-compose.yml Approach
+- Uses `APP_ENV` environment variable to control behavior
+- Dockerfile uses `ENV` build argument for environment-specific builds
+- Same containers work for both development and production
+
+### Environment Variable Control
+- **Development**: `APP_ENV=development`, `APP_DEBUG=true`
+  - Full debug information visible
+  - All routes accessible
+  - Performance tracking enabled
+  
+- **Production**: `APP_ENV=production`, `APP_DEBUG=false`
+  - Debug information hidden
+  - Admin/debug routes blocked
+  - Performance tracking disabled
+  - IP restrictions enforced
+
+## Validation & Testing
+
+### Local Testing Commands
+```bash
+# Test security configuration
+./test-security.sh
+
+# Test with production environment locally
+docker exec php bash -c "cp .env.production .env && php test-production-config.php"
+
+# Restore development environment
+docker exec php cp .env.production.backup .env
+```
+
+### Deployment Validation
+The deployment script now automatically:
+1. Validates `APP_ENV=production` and `APP_DEBUG=false`
+2. Tests that debug routes return 404
+3. Confirms environment is properly configured
+
+### Manual Production Testing
+After deployment, verify from external IP:
+```bash
+# Should return 404
+curl -H "User-Agent: Mozilla/5.0" https://michaelschiemer.de/debug
+curl -H "User-Agent: Mozilla/5.0" https://michaelschiemer.de/admin/discovery
+
+# Should return 403 (unless your IP is whitelisted)
+curl -H "User-Agent: Mozilla/5.0" https://michaelschiemer.de/admin
+curl -H "User-Agent: Mozilla/5.0" https://michaelschiemer.de/health
+```
+
+## Key Security Improvements
+
+1. **Zero Debug Information Leakage**: No performance data, session info, or debug details in production
+2. **Route-Level Security**: Admin and debug routes completely blocked (404 response)
+3. **IP-Based Access Control**: Critical routes restricted to whitelisted IPs
+4. **Environment Validation**: Automatic validation during deployment
+5. **Single Configuration**: One docker-compose.yml handles both dev and prod modes
+
+## Deployment Process
+
+1. **Pre-deployment**: Local testing with production environment simulation
+2. **Deployment**: Automatic copy of `.env.production` to `.env` 
+3. **Validation**: Automatic environment and security testing
+4. **Verification**: Manual testing of critical security endpoints
+
+The system now provides robust production security while maintaining development flexibility through environment-based configuration.

docs/deployment/SSL-PRODUCTION-SETUP.md

@@ -0,0 +1,195 @@
+# Production SSL Setup for michaelschiemer.de
+
+This guide explains how to fix the SSL configuration for the production domain https://michaelschiemer.de/
+
+## Current Status
+
+✅ **Nginx Configuration Fixed**
+- Updated server_name from `localhost` to `localhost michaelschiemer.de` 
+- Both HTTP redirect and HTTPS server blocks now support the production domain
+- Health check mapping updated to allow `michaelschiemer.de` domain
+
+✅ **Deployment Script Enhanced**
+- Added SSL certificate checks in `deploy.sh`
+- Automatic creation of temporary self-signed certificates if Let's Encrypt certificates are missing
+- Ensures Docker containers can start even without valid SSL certificates
+
+## Setup Instructions
+
+### Step 1: Deploy Updated Configuration
+
+```bash
+# Deploy the updated nginx configuration
+./deploy.sh
+```
+
+This will deploy the updated nginx configuration and create temporary self-signed certificates if needed.
+
+### Step 2: Generate Let's Encrypt SSL Certificates
+
+**Important**: Make sure `michaelschiemer.de` points to your server IP `94.16.110.151` before running this.
+
+```bash
+# Run the SSL setup script
+./setup-production-ssl.sh
+```
+
+This script will:
+- Check DNS resolution for the domain
+- Install certbot on the production server
+- Stop nginx temporarily
+- Generate Let's Encrypt certificates using HTTP-01 challenge
+- Copy certificates to the expected location (`/var/www/ssl/`)
+- Restart the application with valid SSL certificates
+- Set up automatic certificate renewal (twice daily)
+
+### Step 3: Verify SSL Setup
+
+1. **Test HTTPS Access**:
+   ```bash
+   curl -I https://michaelschiemer.de/
+   ```
+
+2. **Check Certificate Details**:
+   ```bash
+   echo | openssl s_client -servername michaelschiemer.de -connect michaelschiemer.de:443 2>/dev/null | openssl x509 -noout -dates
+   ```
+
+3. **Verify Docker Containers**:
+   ```bash
+   ssh deploy@94.16.110.151 'cd /home/deploy/michaelschiemer && docker compose ps'
+   ```
+
+## Configuration Changes Made
+
+### 1. Nginx Configuration (`docker/nginx/default.conf`)
+
+**Health Check Mapping**:
+```nginx
+map $host $block_health {
+    default 1;              # Block everything by default
+    localhost 0;            # Allow localhost (development)
+    michaelschiemer.de 0;   # Allow production domain
+}
+```
+
+**HTTP Server Block**:
+```nginx
+server {
+    listen 80;
+    server_name localhost michaelschiemer.de;  # Support both domains
+    return 301 https://$host$request_uri;
+}
+```
+
+**HTTPS Server Block**:
+```nginx
+server {
+    listen 443 ssl;
+    server_name localhost michaelschiemer.de;  # Support both domains
+    
+    ssl_certificate /var/www/ssl/fullchain.pem;
+    ssl_certificate_key /var/www/ssl/privkey.pem;
+    # ... rest of SSL configuration
+}
+```
+
+### 2. Docker Compose Volume Mounting
+
+SSL certificates are mounted from `./ssl` to `/var/www/ssl` in the nginx container:
+
+```yaml
+volumes:
+  - ./ssl:/var/www/ssl:ro
+```
+
+### 3. Enhanced Deployment Script
+
+The deployment script now:
+- Checks for existing SSL certificates
+- Creates temporary self-signed certificates if Let's Encrypt certificates are missing
+- Ensures the application can start regardless of certificate status
+
+## Certificate Renewal
+
+Automatic renewal is set up with a cron job that runs twice daily:
+```bash
+0 12,0 * * * /home/deploy/renew-certificates.sh >> /var/log/letsencrypt-renewal.log 2>&1
+```
+
+The renewal script:
+1. Stops the nginx container
+2. Renews certificates using certbot
+3. Copies renewed certificates to the correct location
+4. Restarts all services
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Domain not resolving to server IP**:
+   ```bash
+   dig +short michaelschiemer.de
+   # Should return: 94.16.110.151
+   ```
+
+2. **Firewall blocking port 80/443**:
+   ```bash
+   # Check if ports are open
+   nmap -p 80,443 94.16.110.151
+   ```
+
+3. **Certificate generation fails**:
+   - Ensure domain points to server IP
+   - Check if port 80 is accessible from internet
+   - Verify no other services are using port 80 during certificate generation
+
+4. **Docker container won't start**:
+   ```bash
+   # Check container logs
+   ssh deploy@94.16.110.151 'cd /home/deploy/michaelschiemer && docker compose logs web'
+   ```
+
+### Manual Certificate Check
+
+```bash
+# SSH to production server
+ssh deploy@94.16.110.151
+
+# Check certificate files
+ls -la /home/deploy/michaelschiemer/ssl/
+cat /home/deploy/michaelschiemer/ssl/fullchain.pem | openssl x509 -noout -text
+```
+
+### Force Certificate Regeneration
+
+```bash
+# SSH to production server
+ssh deploy@94.16.110.151
+
+cd /home/deploy/michaelschiemer
+
+# Remove existing certificates
+rm -rf ssl/live ssl/archive ssl/*.pem
+
+# Run the SSL setup script again
+./setup-production-ssl.sh
+```
+
+## Security Considerations
+
+1. **Certificate Storage**: Certificates are stored in `/var/www/ssl/` and mounted read-only in containers
+2. **Automatic Renewal**: Certificates automatically renew before expiration
+3. **Strong SSL Configuration**: TLS 1.2+ with secure cipher suites
+4. **Security Headers**: HSTS, CSP, and other security headers configured
+5. **HTTP to HTTPS Redirect**: All HTTP traffic redirected to HTTPS
+
+## Next Steps After SSL Setup
+
+1. **Test the Application**: Visit https://michaelschiemer.de/
+2. **Monitor Logs**: Check nginx and application logs for any issues
+3. **Set up Monitoring**: Consider setting up SSL certificate expiration monitoring
+4. **Performance Testing**: Run performance tests with SSL enabled
+5. **Security Audit**: Run SSL Labs test: https://www.ssllabs.com/ssltest/
+
+The SSL configuration is now production-ready and should provide secure HTTPS access to your Custom PHP Framework application.