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

src/Domain/Media/Migrations/CreateImageSlotsTable.php

@@ -7,30 +7,37 @@ namespace App\Domain\Media\Migrations;
 use App\Framework\Database\ConnectionInterface;
 use App\Framework\Database\Migration\Migration;
 use App\Framework\Database\Migration\MigrationVersion;
+use App\Framework\Database\Platform\SchemaBuilderFactory;
+use App\Framework\Database\Platform\ValueObjects\TableOptions;
 
 final readonly class CreateImageSlotsTable implements Migration
 {
     public function up(ConnectionInterface $connection): void
     {
-        $sql = <<<SQL
-            CREATE TABLE IF NOT EXISTS image_slots (
-                id              INT AUTO_INCREMENT,
-                image_id        VARCHAR(26) NOT NULL,
-                slot_name       VARCHAR(50) NOT NULL,
-                created_at      TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-                updated_at      TIMESTAMP NULL DEFAULT NULL,
+        $schema = SchemaBuilderFactory::create($connection);
 
-                PRIMARY KEY (id)
-                )
-                ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-SQL;
-
-        $connection->query($sql);
+        $schema->createTable(
+            'image_slots',
+            [
+            $schema->id(),
+            $schema->string('image_id', 26)->notNull(),
+            $schema->string('slot_name', 50)->notNull(),
+            $schema->timestamp('created_at')->notNull()->withDefault('CURRENT_TIMESTAMP'),
+            $schema->timestamp('updated_at')->withDefault(null),
+        ],
+            TableOptions::default()
+            ->withEngine('InnoDB')
+            ->withCharset('utf8mb4')
+            ->withCollation('utf8mb4_unicode_ci')
+            ->withIfNotExists()
+            ->withComment('Image slots table for image slot management')
+        );
     }
 
     public function down(ConnectionInterface $connection): void
     {
-        $connection->execute("DROP TABLE IF EXISTS image_slots");
+        $schema = SchemaBuilderFactory::create($connection);
+        $schema->dropTable('image_slots', true);
     }
 
     public function getVersion(): MigrationVersion

src/Domain/Media/Migrations/CreateImageVariantsTable.php

@@ -7,42 +7,53 @@ namespace App\Domain\Media\Migrations;
 use App\Framework\Database\ConnectionInterface;
 use App\Framework\Database\Migration\Migration;
 use App\Framework\Database\Migration\MigrationVersion;
+use App\Framework\Database\Platform\SchemaBuilderFactory;
+use App\Framework\Database\Platform\ValueObjects\TableOptions;
 
 final class CreateImageVariantsTable implements Migration
 {
     public function up(ConnectionInterface $connection): void
     {
-        $sql = <<<SQL
-            CREATE TABLE IF NOT EXISTS image_variants (
-                id              INT AUTO_INCREMENT,
-                image_id        VARCHAR(26) NOT NULL,
-                variant_type    VARCHAR(50) NOT NULL,
-                format          VARCHAR(25) NOT NULL,
-                mime_type       VARCHAR(100) NOT NULL,
-                width           INT NOT NULL,
-                height          INT NOT NULL,
-                file_size       BIGINT NOT NULL,
-                filename        VARCHAR(500) NOT NULL,
-                path            VARCHAR(500) NOT NULL,
-                created_at      TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-                updated_at      TIMESTAMP NULL DEFAULT NULL,
+        $schema = SchemaBuilderFactory::create($connection);
 
-                PRIMARY KEY (id),
-                UNIQUE KEY uk_image_variants_combination (image_id, variant_type, format),
-                CONSTRAINT fk_image_variants_image_id
-                    FOREIGN KEY (image_id) REFERENCES images(ulid) ON DELETE CASCADE,
-                INDEX idx_image_variants_lookup (image_id, variant_type)
-            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-SQL;
+        $schema->createTable(
+            'image_variants',
+            [
+            $schema->id(),
+            $schema->string('image_id', 26)->notNull(),
+            $schema->string('variant_type', 50)->notNull(),
+            $schema->string('format', 25)->notNull(),
+            $schema->string('mime_type', 100)->notNull(),
+            $schema->integer('width')->notNull(),
+            $schema->integer('height')->notNull(),
+            $schema->bigInteger('file_size')->notNull(),
+            $schema->string('filename', 500)->notNull(),
+            $schema->string('path', 500)->notNull(),
+            $schema->timestamp('created_at')->notNull()->withDefault('CURRENT_TIMESTAMP'),
+            $schema->timestamp('updated_at')->withDefault(null),
+        ],
+            TableOptions::default()
+            ->withEngine('InnoDB')
+            ->withCharset('utf8mb4')
+            ->withCollation('utf8mb4_unicode_ci')
+            ->withIfNotExists()
+            ->withComment('Image variants table for different image sizes and formats')
+        );
 
-        $connection->query($sql);
+        // TODO: Add unique constraint, foreign key constraint, and index
+        // These will need to be implemented in a future enhancement of the SchemaBuilder
+        // For now, we'll add them manually:
+        $connection->query("ALTER TABLE image_variants ADD UNIQUE KEY uk_image_variants_combination (image_id, variant_type, format)");
+        $connection->query("ALTER TABLE image_variants ADD CONSTRAINT fk_image_variants_image_id FOREIGN KEY (image_id) REFERENCES images(ulid) ON DELETE CASCADE");
+        $connection->query("ALTER TABLE image_variants ADD INDEX idx_image_variants_lookup (image_id, variant_type)");
     }
 
     public function down(ConnectionInterface $connection): void
     {
-        $this->dropExistingConstraints($connection);
+        $schema = SchemaBuilderFactory::create($connection);
 
-        $connection->execute("DROP TABLE IF EXISTS image_variants");
+        $this->dropExistingConstraints($connection);
+        $schema->dropTable('image_variants', true);
     }
 
     public function getVersion(): MigrationVersion

src/Domain/Media/Migrations/CreateImagesTableWithSchema.php

@@ -16,7 +16,7 @@ final class CreateImagesTableWithSchema implements Migration
     {
         $schema = new Schema($connection);
 
-        $schema->create('images', function (Blueprint $table) {
+        $schema->createIfNotExists('images', function (Blueprint $table) {
             $table->ulid('ulid')->primary();
             $table->string('filename', 255);
             $table->string('original_filename', 255);