michaelschiemer/docs/planning/CLEANUP_PLAN.md

# Root Directory Cleanup Plan

## 1. Files to Move

### Debug Scripts → scripts/debug/
```bash
mv debug_*.php scripts/debug/
mv test_*.php scripts/test/
mv simple_debug_tui.php scripts/debug/
mv populate_images_from_filesystem.php scripts/maintenance/
mv websocket.php scripts/test/
```

### Documentation → docs/
```bash
# Root markdown files to consolidate
mv AUTOLOADER_WORKAROUND.md docs/troubleshooting/
mv DEPLOYMENT*.md docs/deployment/
mv SSL-PRODUCTION-SETUP.md docs/deployment/
mv PRODUCTION-SECURITY-UPDATES.md docs/deployment/
mv README-*.md docs/guides/
mv TODO.md docs/
mv docs-*.md docs/planning/
```

### Public Directory Security Cleanup
```bash
# REMOVE from public/ (move to scripts/debug/)
mv public/debug.php scripts/debug/
mv public/test.php scripts/test/
mv public/security-test.php scripts/debug/
mv public/production-test.php scripts/debug/
mv public/quick-fix.php scripts/debug/
mv public/build-container.php scripts/debug/
mv public/force-production-test.php scripts/debug/
mv public/dev-hot-reload*.php scripts/debug/
mv public/minimal.php scripts/debug/

# public/ should only contain:
# - index.php (production entry point)
# - health.php (monitoring)
# - .vite/ (build artifacts)
# - assets/ (compiled assets)
```

## 2. New Directory Structure

```
michaelschiemer/
├── bin/                          # Executable scripts
│   ├── console                   # Symlink to console.php
│   └── worker                    # Symlink to worker.php
├── config/                       # Configuration files
│   └── static-routes.json
├── docs/                         # Consolidated documentation
│   ├── README.md
│   ├── architecture/
│   │   ├── framework-principles.md
│   │   ├── di-container.md
│   │   └── discovery-system.md
│   ├── deployment/
│   │   ├── production-setup.md
│   │   ├── ssl-configuration.md
│   │   └── docker-guide.md
│   ├── guides/
│   │   ├── getting-started.md
│   │   ├── api-versioning.md
│   │   └── testing.md
│   ├── troubleshooting/
│   │   ├── autoloader-workaround.md
│   │   └── common-issues.md
│   └── planning/
│       └── TODO.md
├── public/                       # Web-accessible (MINIMAL!)
│   ├── index.php
│   ├── health.php
│   └── .vite/
├── resources/                    # Source assets
│   ├── css/
│   └── js/
├── scripts/                      # Development & maintenance
│   ├── debug/                   # Debug scripts (NOT web-accessible)
│   ├── test/                    # Test scripts
│   ├── deployment/              # Deployment scripts
│   └── maintenance/             # Maintenance scripts
├── src/                         # Application source
├── storage/                     # Runtime data
│   ├── cache/                   # Add to .gitignore
│   ├── logs/
│   └── uploads/
├── tests/                       # Test suite
├── vendor/                      # Composer dependencies
└── var/                         # Temporary files
    └── phpstan/cache/           # Add to .gitignore
```

## 3. Gitignore Updates

Add to `.gitignore`:
```
# Cache
storage/cache/*.cache.php
storage/cache/*.php

# PHPStan
var/phpstan/cache/**

# Logs
storage/logs/*.log

# Temporary debug files
scripts/debug/output/
scripts/test/output/
```

## 4. Immediate Actions

### Priority 1: Security (DO IMMEDIATELY!)
```bash
# Remove debug files from public/
rm public/debug.php
rm public/test.php
rm public/security-test.php
rm public/production-test.php
rm public/quick-fix.php
rm public/build-container.php
rm public/force-production-test.php
rm public/dev-hot-reload.php
rm public/dev-hot-reload-minimal.php
rm public/minimal.php
```

### Priority 2: Cache Cleanup
```bash
# Clear old cache files
find storage/cache -name "*.cache.php" -mtime +7 -delete
find var/phpstan/cache -type f -mtime +7 -delete
```

### Priority 3: Documentation Consolidation
```bash
# Create new structure
mkdir -p docs/{architecture,deployment,guides,troubleshooting,planning}
mkdir -p scripts/{debug,test,deployment,maintenance}

# Move files (execute moves from section 1)
```

## 5. Benefits

- ✅ **Security**: No debug code in public/
- ✅ **Organization**: Clear separation of concerns
- ✅ **Performance**: Cleaner cache structure
- ✅ **Developer Experience**: Easy navigation
- ✅ **Professional**: Clean root directory
- ✅ **Maintainability**: Consolidated documentation

## 6. Automated Cleanup Script

Create `scripts/maintenance/cleanup-project.php`:
```php
#!/usr/bin/env php
<?php
// Automated cleanup script
// - Clear old cache files
// - Remove temporary files
// - Validate directory structure
```

## Execution Timeline

**Week 1**:
- Security cleanup (public/ directory)
- Cache cleanup

**Week 2**:
- Documentation consolidation
- Root directory organization

**Week 3**:
- Script organization
- Automated cleanup tools

**Week 4**:
- Validation & testing
- Update documentation