michaelschiemer/docs/planning/CLEANUP_PLAN.md

Root Directory Cleanup Plan

1. Files to Move

Debug Scripts → scripts/debug/

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/

# 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

# 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!)

# 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

# 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

# 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:

#!/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