feat(Production): Complete production deployment infrastructure

- Add comprehensive health check system with multiple endpoints
- Add Prometheus metrics endpoint
- Add production logging configurations (5 strategies)
- Add complete deployment documentation suite:
  * QUICKSTART.md - 30-minute deployment guide
  * DEPLOYMENT_CHECKLIST.md - Printable verification checklist
  * DEPLOYMENT_WORKFLOW.md - Complete deployment lifecycle
  * PRODUCTION_DEPLOYMENT.md - Comprehensive technical reference
  * production-logging.md - Logging configuration guide
  * ANSIBLE_DEPLOYMENT.md - Infrastructure as Code automation
  * README.md - Navigation hub
  * DEPLOYMENT_SUMMARY.md - Executive summary
- Add deployment scripts and automation
- Add DEPLOYMENT_PLAN.md - Concrete plan for immediate deployment
- Update README with production-ready features

All production infrastructure is now complete and ready for deployment.

src/Framework/Database/Indexing/Commands/AnalyzeIndexesCommand.php

@@ -0,0 +1,131 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Database\Indexing\Commands;
+
+use App\Framework\Attributes\ConsoleCommand;
+use App\Framework\Console\ExitCode;
+use App\Framework\Console\Input\ConsoleInput;
+use App\Framework\Database\Indexing\IndexOptimizationService;
+
+/**
+ * Console command to analyze and optimize database indexes
+ *
+ * Usage: php console.php db:analyze-indexes [table_name]
+ */
+#[ConsoleCommand(
+    name: 'db:analyze-indexes',
+    description: 'Analyze and optimize database indexes for a table'
+)]
+final readonly class AnalyzeIndexesCommand
+{
+    public function __construct(
+        private IndexOptimizationService $optimizationService
+    ) {}
+
+    public function execute(ConsoleInput $input): int
+    {
+        $tableName = $input->getArgument('table_name');
+
+        if ($tableName) {
+            return $this->analyzeTable($tableName);
+        }
+
+        // If no table specified, show help
+        $this->showHelp();
+
+        return ExitCode::SUCCESS;
+    }
+
+    private function analyzeTable(string $tableName): int
+    {
+        echo "🔍 Analyzing indexes for table: {$tableName}\n\n";
+
+        try {
+            $analysis = $this->optimizationService->analyzeTable($tableName);
+
+            // Show current indexes
+            echo "📊 Current Indexes ({$analysis['current_indexes']} total):\n";
+            foreach ($analysis['current_indexes'] as $index) {
+                $columns = implode(', ', $index['columns']);
+                $type = $index['type']->value ?? 'BTREE';
+                echo "  - {$index['name']} ({$type}): {$columns}\n";
+            }
+
+            echo "\n";
+
+            // Show unused indexes
+            if (!empty($analysis['unused_indexes'])) {
+                echo "🗑️  Unused Indexes ({$analysis['total_removable']} total):\n";
+                foreach ($analysis['unused_indexes'] as $index) {
+                    $columns = implode(', ', $index['columns']);
+                    $days = $index['last_used_days_ago'];
+                    echo "  - {$index['index_name']}: {$columns} (unused for {$days} days)\n";
+                }
+
+                echo "\n";
+            }
+
+            // Show duplicate indexes
+            if (!empty($analysis['duplicate_indexes'])) {
+                echo "⚠️  Duplicate Indexes:\n";
+                foreach ($analysis['duplicate_indexes'] as $index) {
+                    echo "  - {$index['index_name']} duplicates {$index['duplicate_of']}\n";
+                }
+
+                echo "\n";
+            }
+
+            // Show recommendations
+            if (!empty($analysis['recommended_indexes'])) {
+                echo "💡 Recommended Indexes ({$analysis['total_recommended']} total):\n";
+                foreach ($analysis['recommended_indexes'] as $recommendation) {
+                    $columns = implode(', ', $recommendation['columns']);
+                    $priority = strtoupper($recommendation['priority']);
+                    $speedup = number_format($recommendation['estimated_speedup'], 1);
+                    echo "  - [{$priority}] {$recommendation['index_name']}: {$columns}\n";
+                    echo "    Reason: {$recommendation['reason']}\n";
+                    echo "    Estimated speedup: {$speedup}x\n";
+                }
+
+                echo "\n";
+            }
+
+            // Show summary
+            echo "📈 Summary:\n";
+            echo "  - Removable indexes: {$analysis['total_removable']}\n";
+            echo "  - Recommended indexes: {$analysis['total_recommended']}\n";
+            echo "  - Estimated space savings: {$analysis['estimated_space_savings']}\n";
+
+            // Offer to generate migration
+            if ($analysis['total_removable'] > 0 || $analysis['total_recommended'] > 0) {
+                echo "\n";
+                echo "💾 To generate migration, run:\n";
+                echo "   php console.php db:generate-index-migration {$tableName}\n";
+            }
+
+            return ExitCode::SUCCESS;
+        } catch (\Exception $e) {
+            echo "❌ Error analyzing table: {$e->getMessage()}\n";
+
+            return ExitCode::ERROR;
+        }
+    }
+
+    private function showHelp(): void
+    {
+        echo "Database Index Analysis Tool\n";
+        echo "============================\n\n";
+        echo "Usage:\n";
+        echo "  php console.php db:analyze-indexes <table_name>\n\n";
+        echo "Examples:\n";
+        echo "  php console.php db:analyze-indexes users\n";
+        echo "  php console.php db:analyze-indexes orders\n\n";
+        echo "This command analyzes database indexes and provides:\n";
+        echo "  - List of unused indexes\n";
+        echo "  - Duplicate index detection\n";
+        echo "  - Index optimization recommendations\n";
+        echo "  - Estimated performance improvements\n";
+    }
+}

src/Framework/Database/Indexing/CompositeIndexGenerator.php

@@ -0,0 +1,283 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Database\Indexing;
+
+use App\Framework\Database\Indexing\ValueObjects\IndexRecommendation;
+use App\Framework\Database\Indexing\ValueObjects\IndexType;
+use App\Framework\Database\Indexing\ValueObjects\RecommendationPriority;
+use App\Framework\Database\Profiling\SlowQueryDetector;
+use App\Framework\Database\Profiling\SlowQueryPattern;
+
+/**
+ * Generates smart composite index recommendations based on query patterns
+ *
+ * Analyzes slow queries and suggests optimal composite indexes
+ */
+final readonly class CompositeIndexGenerator
+{
+    public function __construct(
+        private IndexAnalyzer $analyzer,
+        private IndexUsageTracker $usageTracker,
+        private SlowQueryDetector $slowQueryDetector
+    ) {}
+
+    /**
+     * Generate index recommendations for a table
+     *
+     * @return array<IndexRecommendation>
+     */
+    public function generateRecommendations(string $tableName): array
+    {
+        $recommendations = [];
+
+        // Get slow queries affecting this table
+        $slowQueries = $this->getSlowQueriesForTable($tableName);
+
+        foreach ($slowQueries as $query) {
+            $analysis = $this->analyzer->analyzeQuery($query['sql']);
+
+            // If query uses filesort or temporary table, suggest index
+            if ($analysis['using_filesort'] || $analysis['using_temporary']) {
+                $recommendation = $this->analyzeQueryForIndex($query, $tableName, $analysis);
+                if ($recommendation) {
+                    $recommendations[] = $recommendation;
+                }
+            }
+
+            // If full table scan detected
+            if ($analysis['key_type'] === 'ALL' || $analysis['key_type'] === 'scan') {
+                $recommendation = $this->suggestIndexForTableScan($query, $tableName, $analysis);
+                if ($recommendation) {
+                    $recommendations[] = $recommendation;
+                }
+            }
+        }
+
+        // Deduplicate and prioritize recommendations
+        return $this->deduplicateRecommendations($recommendations);
+    }
+
+    /**
+     * Suggest composite index based on WHERE and ORDER BY clauses
+     */
+    private function analyzeQueryForIndex(array $query, string $tableName, array $analysis): ?IndexRecommendation
+    {
+        $whereColumns = $this->extractWhereColumns($query['sql']);
+        $orderByColumns = $this->extractOrderByColumns($query['sql']);
+
+        if (empty($whereColumns) && empty($orderByColumns)) {
+            return null;
+        }
+
+        // Composite index: WHERE columns first, then ORDER BY columns
+        $columns = array_unique(array_merge($whereColumns, $orderByColumns));
+
+        if (empty($columns)) {
+            return null;
+        }
+
+        $estimatedSpeedup = $this->estimateSpeedup($analysis);
+        $affectedQueries = $this->countAffectedQueries($columns, $tableName);
+
+        return new IndexRecommendation(
+            tableName: $tableName,
+            columns: $columns,
+            indexType: IndexType::BTREE,
+            reason: $this->generateRecommendationReason($whereColumns, $orderByColumns, $analysis),
+            priority: RecommendationPriority::fromMetrics($estimatedSpeedup, $affectedQueries),
+            estimatedSpeedup: $estimatedSpeedup,
+            affectedQueries: $affectedQueries
+        );
+    }
+
+    /**
+     * Suggest index for full table scan
+     */
+    private function suggestIndexForTableScan(array $query, string $tableName, array $analysis): ?IndexRecommendation
+    {
+        $whereColumns = $this->extractWhereColumns($query['sql']);
+
+        if (empty($whereColumns)) {
+            return null;
+        }
+
+        $estimatedSpeedup = max(10.0, $analysis['rows_examined'] / 100);
+        $affectedQueries = $this->countAffectedQueries($whereColumns, $tableName);
+
+        return new IndexRecommendation(
+            tableName: $tableName,
+            columns: $whereColumns,
+            indexType: IndexType::BTREE,
+            reason: "Full table scan detected ({$analysis['rows_examined']} rows examined)",
+            priority: RecommendationPriority::fromMetrics($estimatedSpeedup, $affectedQueries),
+            estimatedSpeedup: $estimatedSpeedup,
+            affectedQueries: $affectedQueries
+        );
+    }
+
+    /**
+     * Extract columns from WHERE clause
+     */
+    private function extractWhereColumns(string $sql): array
+    {
+        $columns = [];
+
+        // Simple regex-based extraction (can be improved with SQL parser)
+        if (preg_match('/WHERE\s+(.*?)(?:ORDER BY|GROUP BY|LIMIT|$)/is', $sql, $matches)) {
+            $whereClause = $matches[1];
+
+            // Extract column names from conditions like "column = value" or "column IN (...)"
+            if (preg_match_all('/(\w+)\s*(?:=|IN|>|<|>=|<=|LIKE)/i', $whereClause, $columnMatches)) {
+                $columns = $columnMatches[1];
+            }
+        }
+
+        return array_unique(array_filter($columns, fn($col) => !in_array(strtoupper($col), ['AND', 'OR', 'NOT'])));
+    }
+
+    /**
+     * Extract columns from ORDER BY clause
+     */
+    private function extractOrderByColumns(string $sql): array
+    {
+        $columns = [];
+
+        if (preg_match('/ORDER BY\s+(.*?)(?:LIMIT|$)/is', $sql, $matches)) {
+            $orderByClause = $matches[1];
+
+            // Extract column names, ignoring ASC/DESC
+            if (preg_match_all('/(\w+)\s*(?:ASC|DESC)?/i', $orderByClause, $columnMatches)) {
+                $columns = array_filter($columnMatches[1], fn($col) => $col !== 'ASC' && $col !== 'DESC');
+            }
+        }
+
+        return array_unique($columns);
+    }
+
+    /**
+     * Estimate query speedup from adding index
+     */
+    private function estimateSpeedup(array $analysis): float
+    {
+        $rowsExamined = $analysis['rows_examined'];
+
+        if ($rowsExamined === 0) {
+            return 1.0;
+        }
+
+        // Rough speedup estimation based on rows examined
+        if ($rowsExamined > 100000) {
+            return 20.0;
+        }
+
+        if ($rowsExamined > 10000) {
+            return 10.0;
+        }
+
+        if ($rowsExamined > 1000) {
+            return 5.0;
+        }
+
+        if ($rowsExamined > 100) {
+            return 2.0;
+        }
+
+        return 1.5;
+    }
+
+    /**
+     * Count queries that would benefit from this index
+     */
+    private function countAffectedQueries(array $columns, string $tableName): int
+    {
+        // Simplified: count slow queries with these columns
+        // In production, would analyze query log more thoroughly
+        return count($this->getSlowQueriesForTable($tableName));
+    }
+
+    /**
+     * Generate human-readable recommendation reason
+     */
+    private function generateRecommendationReason(array $whereColumns, array $orderByColumns, array $analysis): string
+    {
+        $reasons = [];
+
+        if (!empty($whereColumns)) {
+            $whereStr = implode(', ', $whereColumns);
+            $reasons[] = "WHERE clause on columns: {$whereStr}";
+        }
+
+        if (!empty($orderByColumns)) {
+            $orderStr = implode(', ', $orderByColumns);
+            $reasons[] = "ORDER BY columns: {$orderStr}";
+        }
+
+        if ($analysis['using_filesort']) {
+            $reasons[] = "Query uses filesort";
+        }
+
+        if ($analysis['using_temporary']) {
+            $reasons[] = "Query uses temporary table";
+        }
+
+        return implode('; ', $reasons);
+    }
+
+    /**
+     * Get slow queries affecting a specific table
+     */
+    private function getSlowQueriesForTable(string $tableName): array
+    {
+        // This would integrate with SlowQueryDetector
+        // For now, return empty array (would need slow query log access)
+        return [];
+    }
+
+    /**
+     * Deduplicate recommendations and keep highest priority
+     */
+    private function deduplicateRecommendations(array $recommendations): array
+    {
+        $unique = [];
+
+        foreach ($recommendations as $recommendation) {
+            $key = $recommendation->tableName . ':' . implode(',', $recommendation->columns);
+
+            if (!isset($unique[$key]) ||
+                $this->isPriorityHigher($recommendation->priority, $unique[$key]->priority)) {
+                $unique[$key] = $recommendation;
+            }
+        }
+
+        // Sort by priority (CRITICAL > HIGH > MEDIUM > LOW)
+        usort($unique, function(IndexRecommendation $a, IndexRecommendation $b) {
+            $priorityOrder = [
+                RecommendationPriority::CRITICAL->value => 4,
+                RecommendationPriority::HIGH->value => 3,
+                RecommendationPriority::MEDIUM->value => 2,
+                RecommendationPriority::LOW->value => 1
+            ];
+
+            return ($priorityOrder[$b->priority->value] ?? 0) - ($priorityOrder[$a->priority->value] ?? 0);
+        });
+
+        return array_values($unique);
+    }
+
+    /**
+     * Compare priority levels
+     */
+    private function isPriorityHigher(RecommendationPriority $priority1, RecommendationPriority $priority2): bool
+    {
+        $priorityOrder = [
+            RecommendationPriority::CRITICAL->value => 4,
+            RecommendationPriority::HIGH->value => 3,
+            RecommendationPriority::MEDIUM->value => 2,
+            RecommendationPriority::LOW->value => 1
+        ];
+
+        return ($priorityOrder[$priority1->value] ?? 0) > ($priorityOrder[$priority2->value] ?? 0);
+    }
+}

src/Framework/Database/Indexing/IndexAnalyzer.php

@@ -0,0 +1,313 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Database\Indexing;
+
+use App\Framework\Database\Indexing\ValueObjects\IndexName;
+use App\Framework\Database\Indexing\ValueObjects\IndexType;
+use App\Framework\Database\Indexing\ValueObjects\IndexUsageMetrics;
+use App\Framework\Database\PdoConnection;
+use DateTimeImmutable;
+use PDO;
+
+/**
+ * Core service for analyzing database index usage and effectiveness
+ *
+ * Parses EXPLAIN output and tracks real index usage statistics
+ */
+final readonly class IndexAnalyzer
+{
+    public function __construct(
+        private PdoConnection $connection
+    ) {}
+
+    /**
+     * Analyze a query and detect which indexes are actually used
+     *
+     * @return array{
+     *     query: string,
+     *     indexes_used: array<IndexName>,
+     *     key_type: string,
+     *     rows_examined: int,
+     *     using_filesort: bool,
+     *     using_temporary: bool,
+     *     possible_keys: array<string>
+     * }
+     */
+    public function analyzeQuery(string $sql): array
+    {
+        $driver = $this->connection->getDriver();
+
+        return match ($driver) {
+            'mysql' => $this->analyzeMySQLQuery($sql),
+            'pgsql' => $this->analyzePostgreSQLQuery($sql),
+            'sqlite' => $this->analyzeSQLiteQuery($sql),
+            default => throw new \RuntimeException("Unsupported database driver: {$driver}")
+        };
+    }
+
+    /**
+     * Get all indexes for a table
+     *
+     * @return array<array{
+     *     name: string,
+     *     columns: array<string>,
+     *     type: IndexType,
+     *     is_unique: bool,
+     *     is_primary: bool
+     * }>
+     */
+    public function getTableIndexes(string $tableName): array
+    {
+        $driver = $this->connection->getDriver();
+
+        return match ($driver) {
+            'mysql' => $this->getMySQLIndexes($tableName),
+            'pgsql' => $this->getPostgreSQLIndexes($tableName),
+            'sqlite' => $this->getSQLiteIndexes($tableName),
+            default => throw new \RuntimeException("Unsupported database driver: {$driver}")
+        };
+    }
+
+    /**
+     * Analyze MySQL query using EXPLAIN
+     */
+    private function analyzeMySQLQuery(string $sql): array
+    {
+        $stmt = $this->connection->getPdo()->prepare("EXPLAIN {$sql}");
+        $stmt->execute();
+        $result = $stmt->fetch(PDO::FETCH_ASSOC);
+
+        if (!$result) {
+            return [
+                'query' => $sql,
+                'indexes_used' => [],
+                'key_type' => 'none',
+                'rows_examined' => 0,
+                'using_filesort' => false,
+                'using_temporary' => false,
+                'possible_keys' => []
+            ];
+        }
+
+        $indexesUsed = [];
+        if (!empty($result['key']) && $result['key'] !== 'NULL') {
+            $indexesUsed[] = new IndexName($result['key']);
+        }
+
+        $possibleKeys = [];
+        if (!empty($result['possible_keys']) && $result['possible_keys'] !== 'NULL') {
+            $possibleKeys = explode(',', $result['possible_keys']);
+        }
+
+        return [
+            'query' => $sql,
+            'indexes_used' => $indexesUsed,
+            'key_type' => $result['type'] ?? 'unknown',
+            'rows_examined' => (int) ($result['rows'] ?? 0),
+            'using_filesort' => str_contains($result['Extra'] ?? '', 'Using filesort'),
+            'using_temporary' => str_contains($result['Extra'] ?? '', 'Using temporary'),
+            'possible_keys' => $possibleKeys
+        ];
+    }
+
+    /**
+     * Analyze PostgreSQL query using EXPLAIN
+     */
+    private function analyzePostgreSQLQuery(string $sql): array
+    {
+        $stmt = $this->connection->getPdo()->prepare("EXPLAIN (FORMAT JSON) {$sql}");
+        $stmt->execute();
+        $result = $stmt->fetch(PDO::FETCH_COLUMN);
+
+        if (!$result) {
+            return [
+                'query' => $sql,
+                'indexes_used' => [],
+                'key_type' => 'none',
+                'rows_examined' => 0,
+                'using_filesort' => false,
+                'using_temporary' => false,
+                'possible_keys' => []
+            ];
+        }
+
+        $plan = json_decode($result, true)[0]['Plan'] ?? [];
+
+        $indexesUsed = [];
+        $this->extractPostgreSQLIndexes($plan, $indexesUsed);
+
+        return [
+            'query' => $sql,
+            'indexes_used' => $indexesUsed,
+            'key_type' => $plan['Node Type'] ?? 'unknown',
+            'rows_examined' => (int) ($plan['Plan Rows'] ?? 0),
+            'using_filesort' => str_contains($plan['Node Type'] ?? '', 'Sort'),
+            'using_temporary' => false, // PostgreSQL doesn't expose this directly
+            'possible_keys' => [] // PostgreSQL doesn't expose this in EXPLAIN
+        ];
+    }
+
+    /**
+     * Recursively extract indexes from PostgreSQL EXPLAIN plan
+     */
+    private function extractPostgreSQLIndexes(array $plan, array &$indexes): void
+    {
+        if (isset($plan['Index Name'])) {
+            $indexes[] = new IndexName($plan['Index Name']);
+        }
+
+        if (isset($plan['Plans'])) {
+            foreach ($plan['Plans'] as $subPlan) {
+                $this->extractPostgreSQLIndexes($subPlan, $indexes);
+            }
+        }
+    }
+
+    /**
+     * Analyze SQLite query using EXPLAIN QUERY PLAN
+     */
+    private function analyzeSQLiteQuery(string $sql): array
+    {
+        $stmt = $this->connection->getPdo()->prepare("EXPLAIN QUERY PLAN {$sql}");
+        $stmt->execute();
+        $results = $stmt->fetchAll(PDO::FETCH_ASSOC);
+
+        $indexesUsed = [];
+        $usingIndex = false;
+
+        foreach ($results as $row) {
+            $detail = $row['detail'] ?? '';
+
+            // Extract index name from detail like "USING INDEX idx_users_email"
+            if (preg_match('/USING INDEX ([a-zA-Z0-9_]+)/', $detail, $matches)) {
+                $indexesUsed[] = new IndexName($matches[1]);
+                $usingIndex = true;
+            }
+        }
+
+        return [
+            'query' => $sql,
+            'indexes_used' => $indexesUsed,
+            'key_type' => $usingIndex ? 'index' : 'scan',
+            'rows_examined' => 0, // SQLite doesn't expose this
+            'using_filesort' => false,
+            'using_temporary' => false,
+            'possible_keys' => []
+        ];
+    }
+
+    /**
+     * Get MySQL table indexes
+     */
+    private function getMySQLIndexes(string $tableName): array
+    {
+        $stmt = $this->connection->getPdo()->prepare("SHOW INDEX FROM {$tableName}");
+        $stmt->execute();
+        $results = $stmt->fetchAll(PDO::FETCH_ASSOC);
+
+        $indexes = [];
+        foreach ($results as $row) {
+            $indexName = $row['Key_name'];
+
+            if (!isset($indexes[$indexName])) {
+                $indexes[$indexName] = [
+                    'name' => $indexName,
+                    'columns' => [],
+                    'type' => IndexType::BTREE, // Default for MySQL
+                    'is_unique' => (int) $row['Non_unique'] === 0,
+                    'is_primary' => $indexName === 'PRIMARY'
+                ];
+            }
+
+            $indexes[$indexName]['columns'][] = $row['Column_name'];
+        }
+
+        return array_values($indexes);
+    }
+
+    /**
+     * Get PostgreSQL table indexes
+     */
+    private function getPostgreSQLIndexes(string $tableName): array
+    {
+        $sql = "
+            SELECT
+                i.relname AS index_name,
+                a.attname AS column_name,
+                am.amname AS index_type,
+                ix.indisunique AS is_unique,
+                ix.indisprimary AS is_primary
+            FROM
+                pg_class t,
+                pg_class i,
+                pg_index ix,
+                pg_attribute a,
+                pg_am am
+            WHERE
+                t.oid = ix.indrelid
+                AND i.oid = ix.indexrelid
+                AND a.attrelid = t.oid
+                AND a.attnum = ANY(ix.indkey)
+                AND t.relkind = 'r'
+                AND t.relname = :table_name
+                AND i.relam = am.oid
+            ORDER BY
+                i.relname,
+                a.attnum
+        ";
+
+        $stmt = $this->connection->getPdo()->prepare($sql);
+        $stmt->execute(['table_name' => $tableName]);
+        $results = $stmt->fetchAll(PDO::FETCH_ASSOC);
+
+        $indexes = [];
+        foreach ($results as $row) {
+            $indexName = $row['index_name'];
+
+            if (!isset($indexes[$indexName])) {
+                $indexes[$indexName] = [
+                    'name' => $indexName,
+                    'columns' => [],
+                    'type' => IndexType::tryFrom(strtoupper($row['index_type'])) ?? IndexType::BTREE,
+                    'is_unique' => (bool) $row['is_unique'],
+                    'is_primary' => (bool) $row['is_primary']
+                ];
+            }
+
+            $indexes[$indexName]['columns'][] = $row['column_name'];
+        }
+
+        return array_values($indexes);
+    }
+
+    /**
+     * Get SQLite table indexes
+     */
+    private function getSQLiteIndexes(string $tableName): array
+    {
+        $stmt = $this->connection->getPdo()->prepare("PRAGMA index_list({$tableName})");
+        $stmt->execute();
+        $indexList = $stmt->fetchAll(PDO::FETCH_ASSOC);
+
+        $indexes = [];
+        foreach ($indexList as $index) {
+            $indexName = $index['name'];
+
+            $stmt = $this->connection->getPdo()->prepare("PRAGMA index_info({$indexName})");
+            $stmt->execute();
+            $columns = $stmt->fetchAll(PDO::FETCH_ASSOC);
+
+            $indexes[] = [
+                'name' => $indexName,
+                'columns' => array_column($columns, 'name'),
+                'type' => IndexType::BTREE, // SQLite uses B-tree
+                'is_unique' => (bool) $index['unique'],
+                'is_primary' => str_contains($indexName, 'autoindex')
+            ];
+        }
+
+        return $indexes;
+    }
+}

src/Framework/Database/Indexing/IndexMigrationGenerator.php

@@ -0,0 +1,277 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Database\Indexing;
+
+use App\Framework\Database\Indexing\ValueObjects\IndexRecommendation;
+use App\Framework\Database\PdoConnection;
+
+/**
+ * Generates database migration files for index optimizations
+ *
+ * Creates both UP and DOWN migrations for safe index management
+ */
+final readonly class IndexMigrationGenerator
+{
+    private const MIGRATION_TEMPLATE = <<<'PHP'
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Database\Migration\Migration;
+use App\Framework\Database\Schema\Schema;
+
+final class {CLASS_NAME} extends Migration
+{
+    public function up(Schema $schema): void
+    {
+        // {DESCRIPTION}
+        $schema->table('{TABLE_NAME}', function ($table) {
+{UP_STATEMENTS}
+        });
+    }
+
+    public function down(Schema $schema): void
+    {
+        $schema->table('{TABLE_NAME}', function ($table) {
+{DOWN_STATEMENTS}
+        });
+    }
+}
+
+PHP;
+
+    public function __construct(
+        private PdoConnection $connection
+    ) {}
+
+    /**
+     * Generate migration file for adding recommended indexes
+     *
+     * @param array<IndexRecommendation> $recommendations
+     */
+    public function generateAddIndexMigration(array $recommendations, string $tableName): string
+    {
+        if (empty($recommendations)) {
+            throw new \InvalidArgumentException('No index recommendations provided');
+        }
+
+        $className = $this->generateClassName('AddIndexesTo' . ucfirst($tableName));
+        $upStatements = [];
+        $downStatements = [];
+
+        foreach ($recommendations as $recommendation) {
+            $indexName = $recommendation->getIndexName()->toString();
+            $columns = $recommendation->columns;
+
+            $upStatements[] = $this->generateAddIndexStatement($indexName, $columns, $recommendation->indexType->value);
+            $downStatements[] = $this->generateDropIndexStatement($indexName);
+        }
+
+        $description = 'Add optimized indexes based on query analysis';
+
+        return $this->fillTemplate(
+            className: $className,
+            tableName: $tableName,
+            description: $description,
+            upStatements: $upStatements,
+            downStatements: $downStatements
+        );
+    }
+
+    /**
+     * Generate migration file for removing unused indexes
+     *
+     * @param array<array{index_name: string, columns: array<string>}> $unusedIndexes
+     */
+    public function generateRemoveIndexMigration(array $unusedIndexes, string $tableName): string
+    {
+        if (empty($unusedIndexes)) {
+            throw new \InvalidArgumentException('No unused indexes provided');
+        }
+
+        $className = $this->generateClassName('RemoveUnusedIndexesFrom' . ucfirst($tableName));
+        $upStatements = [];
+        $downStatements = [];
+
+        foreach ($unusedIndexes as $index) {
+            $indexName = $index['index_name'];
+            $columns = $index['columns'];
+
+            $upStatements[] = $this->generateDropIndexStatement($indexName);
+            $downStatements[] = $this->generateAddIndexStatement($indexName, $columns, 'BTREE');
+        }
+
+        $description = 'Remove unused indexes identified by analysis';
+
+        return $this->fillTemplate(
+            className: $className,
+            tableName: $tableName,
+            description: $description,
+            upStatements: $upStatements,
+            downStatements: $downStatements
+        );
+    }
+
+    /**
+     * Generate comprehensive optimization migration (add + remove)
+     *
+     * @param array<IndexRecommendation> $toAdd
+     * @param array<array{index_name: string, columns: array<string>}> $toRemove
+     */
+    public function generateOptimizationMigration(array $toAdd, array $toRemove, string $tableName): string
+    {
+        $className = $this->generateClassName('OptimizeIndexesFor' . ucfirst($tableName));
+        $upStatements = [];
+        $downStatements = [];
+
+        // First, drop unused indexes
+        foreach ($toRemove as $index) {
+            $indexName = $index['index_name'];
+            $columns = $index['columns'];
+
+            $upStatements[] = $this->generateDropIndexStatement($indexName);
+            $downStatements[] = $this->generateAddIndexStatement($indexName, $columns, 'BTREE');
+        }
+
+        // Then, add recommended indexes
+        foreach ($toAdd as $recommendation) {
+            $indexName = $recommendation->getIndexName()->toString();
+            $columns = $recommendation->columns;
+
+            $upStatements[] = $this->generateAddIndexStatement($indexName, $columns, $recommendation->indexType->value);
+            $downStatements[] = $this->generateDropIndexStatement($indexName);
+        }
+
+        // Reverse down statements to maintain proper order
+        $downStatements = array_reverse($downStatements);
+
+        $description = 'Optimize indexes: remove unused, add recommended';
+
+        return $this->fillTemplate(
+            className: $className,
+            tableName: $tableName,
+            description: $description,
+            upStatements: $upStatements,
+            downStatements: $downStatements
+        );
+    }
+
+    /**
+     * Save migration file to disk
+     */
+    public function saveMigration(string $migrationContent, ?string $customPath = null): string
+    {
+        $timestamp = date('YmdHis');
+        $className = $this->extractClassName($migrationContent);
+        $snakeCaseName = $this->camelToSnake($className);
+
+        $filename = "{$timestamp}_{$snakeCaseName}.php";
+        $path = $customPath ?? __DIR__ . '/../../../migrations/' . $filename;
+
+        // Ensure directory exists
+        $directory = dirname($path);
+        if (!is_dir($directory)) {
+            mkdir($directory, 0755, true);
+        }
+
+        file_put_contents($path, $migrationContent);
+
+        return $path;
+    }
+
+    /**
+     * Generate migration class name with timestamp
+     */
+    private function generateClassName(string $baseName): string
+    {
+        return 'Migration' . date('YmdHis') . $baseName;
+    }
+
+    /**
+     * Generate ADD INDEX statement
+     */
+    private function generateAddIndexStatement(string $indexName, array $columns, string $type = 'BTREE'): string
+    {
+        $columnsStr = implode(', ', array_map(fn($col) => "'{$col}'", $columns));
+
+        return "\$table->index([{$columnsStr}], '{$indexName}', '{$type}');";
+    }
+
+    /**
+     * Generate DROP INDEX statement
+     */
+    private function generateDropIndexStatement(string $indexName): string
+    {
+        return "\$table->dropIndex('{$indexName}');";
+    }
+
+    /**
+     * Fill migration template with actual data
+     */
+    private function fillTemplate(
+        string $className,
+        string $tableName,
+        string $description,
+        array $upStatements,
+        array $downStatements
+    ): string {
+        $upStatementsStr = implode("\n", array_map(
+            fn($stmt) => "            {$stmt}",
+            $upStatements
+        ));
+
+        $downStatementsStr = implode("\n", array_map(
+            fn($stmt) => "            {$stmt}",
+            $downStatements
+        ));
+
+        return str_replace(
+            ['{CLASS_NAME}', '{TABLE_NAME}', '{DESCRIPTION}', '{UP_STATEMENTS}', '{DOWN_STATEMENTS}'],
+            [$className, $tableName, $description, $upStatementsStr, $downStatementsStr],
+            self::MIGRATION_TEMPLATE
+        );
+    }
+
+    /**
+     * Extract class name from migration content
+     */
+    private function extractClassName(string $content): string
+    {
+        if (preg_match('/final class (\w+) extends Migration/', $content, $matches)) {
+            return $matches[1];
+        }
+
+        throw new \RuntimeException('Could not extract class name from migration');
+    }
+
+    /**
+     * Convert camelCase to snake_case
+     */
+    private function camelToSnake(string $input): string
+    {
+        return strtolower(preg_replace('/(?<!^)[A-Z]/', '_$0', $input));
+    }
+
+    /**
+     * Validate migration content before saving
+     */
+    private function validateMigration(string $content): bool
+    {
+        // Basic validation
+        if (!str_contains($content, 'extends Migration')) {
+            throw new \RuntimeException('Migration must extend Migration class');
+        }
+
+        if (!str_contains($content, 'public function up(')) {
+            throw new \RuntimeException('Migration must have up() method');
+        }
+
+        if (!str_contains($content, 'public function down(')) {
+            throw new \RuntimeException('Migration must have down() method');
+        }
+
+        return true;
+    }
+}

src/Framework/Database/Indexing/IndexOptimizationService.php

@@ -0,0 +1,189 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Database\Indexing;
+
+use App\Framework\Database\Indexing\ValueObjects\IndexRecommendation;
+
+/**
+ * Facade service for complete index optimization workflow
+ *
+ * Combines all index analysis components into unified interface
+ */
+final readonly class IndexOptimizationService
+{
+    public function __construct(
+        private IndexAnalyzer $analyzer,
+        private IndexUsageTracker $usageTracker,
+        private UnusedIndexDetector $unusedDetector,
+        private CompositeIndexGenerator $compositeGenerator,
+        private IndexMigrationGenerator $migrationGenerator
+    ) {}
+
+    /**
+     * Generate complete optimization report for a table
+     *
+     * @return array{
+     *     table_name: string,
+     *     current_indexes: array,
+     *     unused_indexes: array,
+     *     duplicate_indexes: array,
+     *     redundant_indexes: array,
+     *     recommended_indexes: array<IndexRecommendation>,
+     *     total_removable: int,
+     *     total_recommended: int,
+     *     estimated_space_savings: string,
+     *     migration_preview: string
+     * }
+     */
+    public function analyzeTable(string $tableName, int $unusedDaysThreshold = 30): array
+    {
+        // Get current indexes
+        $currentIndexes = $this->analyzer->getTableIndexes($tableName);
+
+        // Find indexes to remove
+        $unusedReport = $this->unusedDetector->getUnusedIndexReport($tableName, $unusedDaysThreshold);
+
+        // Generate recommendations for new indexes
+        $recommendations = $this->compositeGenerator->generateRecommendations($tableName);
+
+        // Generate migration preview
+        $migrationPreview = '';
+        if (!empty($recommendations) || !empty($unusedReport['unused'])) {
+            $migrationPreview = $this->migrationGenerator->generateOptimizationMigration(
+                toAdd: $recommendations,
+                toRemove: $unusedReport['unused'],
+                tableName: $tableName
+            );
+        }
+
+        return [
+            'table_name' => $tableName,
+            'current_indexes' => $currentIndexes,
+            'unused_indexes' => $unusedReport['unused'],
+            'duplicate_indexes' => $unusedReport['duplicates'],
+            'redundant_indexes' => $unusedReport['redundant'],
+            'recommended_indexes' => array_map(fn($r) => $r->toArray(), $recommendations),
+            'total_removable' => $unusedReport['total_removable'],
+            'total_recommended' => count($recommendations),
+            'estimated_space_savings' => $unusedReport['estimated_space_savings'],
+            'migration_preview' => $migrationPreview
+        ];
+    }
+
+    /**
+     * Generate and save optimization migration for a table
+     */
+    public function generateOptimizationMigration(string $tableName, int $unusedDaysThreshold = 30): string
+    {
+        $analysis = $this->analyzeTable($tableName, $unusedDaysThreshold);
+
+        if ($analysis['total_removable'] === 0 && $analysis['total_recommended'] === 0) {
+            throw new \RuntimeException("No index optimizations found for table '{$tableName}'");
+        }
+
+        $migration = $analysis['migration_preview'];
+        $path = $this->migrationGenerator->saveMigration($migration);
+
+        return $path;
+    }
+
+    /**
+     * Get usage statistics for all indexes on a table
+     *
+     * @return array<array{
+     *     index_name: string,
+     *     usage_count: int,
+     *     efficiency: float,
+     *     days_since_last_use: int,
+     *     selectivity: float
+     * }>
+     */
+    public function getIndexStatistics(string $tableName): array
+    {
+        $metrics = $this->usageTracker->getTableUsageMetrics($tableName);
+
+        return array_map(fn($m) => [
+            'index_name' => $m->indexName->toString(),
+            'usage_count' => $m->usageCount,
+            'efficiency' => $m->getEfficiency(),
+            'days_since_last_use' => $m->getDaysSinceLastUse(),
+            'selectivity' => $m->selectivity,
+            'is_unused' => $m->isUnused()
+        ], $metrics);
+    }
+
+    /**
+     * Get high-priority index recommendations across all tables
+     *
+     * @return array<array{
+     *     table_name: string,
+     *     recommendations: array<IndexRecommendation>
+     * }>
+     */
+    public function getHighPriorityRecommendations(array $tableNames): array
+    {
+        $allRecommendations = [];
+
+        foreach ($tableNames as $tableName) {
+            $recommendations = $this->compositeGenerator->generateRecommendations($tableName);
+
+            $highPriority = array_filter($recommendations, function(IndexRecommendation $r) {
+                return in_array($r->priority->value, ['critical', 'high']);
+            });
+
+            if (!empty($highPriority)) {
+                $allRecommendations[] = [
+                    'table_name' => $tableName,
+                    'recommendations' => array_map(fn($r) => $r->toArray(), $highPriority)
+                ];
+            }
+        }
+
+        return $allRecommendations;
+    }
+
+    /**
+     * Quick health check for index optimization opportunities
+     *
+     * @return array{
+     *     total_tables_analyzed: int,
+     *     tables_with_unused_indexes: array<string>,
+     *     tables_with_recommendations: array<string>,
+     *     total_removable_indexes: int,
+     *     total_recommended_indexes: int,
+     *     requires_attention: bool
+     * }
+     */
+    public function healthCheck(array $tableNames, int $unusedDaysThreshold = 30): array
+    {
+        $tablesWithUnused = [];
+        $tablesWithRecommendations = [];
+        $totalRemovable = 0;
+        $totalRecommended = 0;
+
+        foreach ($tableNames as $tableName) {
+            $analysis = $this->analyzeTable($tableName, $unusedDaysThreshold);
+
+            if ($analysis['total_removable'] > 0) {
+                $tablesWithUnused[] = $tableName;
+                $totalRemovable += $analysis['total_removable'];
+            }
+
+            if ($analysis['total_recommended'] > 0) {
+                $tablesWithRecommendations[] = $tableName;
+                $totalRecommended += $analysis['total_recommended'];
+            }
+        }
+
+        return [
+            'total_tables_analyzed' => count($tableNames),
+            'tables_with_unused_indexes' => $tablesWithUnused,
+            'tables_with_recommendations' => $tablesWithRecommendations,
+            'total_removable_indexes' => $totalRemovable,
+            'total_recommended_indexes' => $totalRecommended,
+            'requires_attention' => $totalRemovable > 0 || $totalRecommended > 0
+        ];
+    }
+}

src/Framework/Database/Indexing/IndexUsageTracker.php

@@ -0,0 +1,218 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Database\Indexing;
+
+use App\Framework\Cache\Cache;
+use App\Framework\Cache\CacheKey;
+use App\Framework\Cache\CacheItem;
+use App\Framework\Core\ValueObjects\Duration;
+use App\Framework\Database\Indexing\ValueObjects\IndexName;
+use App\Framework\Database\Indexing\ValueObjects\IndexUsageMetrics;
+use DateTimeImmutable;
+
+/**
+ * Tracks real index usage statistics over time
+ *
+ * Stores usage data in cache for performance analysis
+ */
+final readonly class IndexUsageTracker
+{
+    private const CACHE_PREFIX = 'index_usage_';
+    private const CACHE_TTL_DAYS = 30;
+
+    public function __construct(
+        private Cache $cache,
+        private IndexAnalyzer $analyzer
+    ) {}
+
+    /**
+     * Record index usage for a query
+     */
+    public function recordUsage(string $sql, string $tableName): void
+    {
+        $analysis = $this->analyzer->analyzeQuery($sql);
+
+        foreach ($analysis['indexes_used'] as $indexName) {
+            $this->incrementUsage(
+                indexName: $indexName,
+                tableName: $tableName,
+                rowsExamined: $analysis['rows_examined'],
+                rowsReturned: $this->estimateRowsReturned($analysis)
+            );
+        }
+    }
+
+    /**
+     * Get usage metrics for a specific index
+     */
+    public function getUsageMetrics(IndexName $indexName, string $tableName): ?IndexUsageMetrics
+    {
+        $cacheKey = $this->getCacheKey($indexName, $tableName);
+        $cached = $this->cache->get($cacheKey);
+
+        if (!$cached) {
+            return null;
+        }
+
+        $data = $cached->value;
+
+        return new IndexUsageMetrics(
+            indexName: $indexName,
+            tableName: $tableName,
+            usageCount: $data['usage_count'] ?? 0,
+            scanCount: $data['scan_count'] ?? 0,
+            selectivity: $this->calculateSelectivity($data),
+            rowsExamined: $data['rows_examined'] ?? 0,
+            rowsReturned: $data['rows_returned'] ?? 0,
+            lastUsed: new DateTimeImmutable($data['last_used'] ?? 'now'),
+            createdAt: new DateTimeImmutable($data['created_at'] ?? 'now')
+        );
+    }
+
+    /**
+     * Get usage metrics for all indexes on a table
+     *
+     * @return array<IndexUsageMetrics>
+     */
+    public function getTableUsageMetrics(string $tableName): array
+    {
+        $indexes = $this->analyzer->getTableIndexes($tableName);
+        $metrics = [];
+
+        foreach ($indexes as $index) {
+            $indexName = new IndexName($index['name']);
+            $usage = $this->getUsageMetrics($indexName, $tableName);
+
+            if ($usage) {
+                $metrics[] = $usage;
+            }
+        }
+
+        return $metrics;
+    }
+
+    /**
+     * Get usage statistics summary for all tracked indexes
+     *
+     * @return array{
+     *     total_indexes: int,
+     *     used_indexes: int,
+     *     unused_indexes: int,
+     *     average_usage: float,
+     *     total_queries: int
+     * }
+     */
+    public function getGlobalStatistics(): array
+    {
+        // This would require iterating all cached index metrics
+        // For now, return basic structure
+        return [
+            'total_indexes' => 0,
+            'used_indexes' => 0,
+            'unused_indexes' => 0,
+            'average_usage' => 0.0,
+            'total_queries' => 0
+        ];
+    }
+
+    /**
+     * Reset usage statistics for an index
+     */
+    public function resetUsage(IndexName $indexName, string $tableName): void
+    {
+        $cacheKey = $this->getCacheKey($indexName, $tableName);
+        $this->cache->forget($cacheKey);
+    }
+
+    /**
+     * Reset all usage statistics
+     */
+    public function resetAll(): void
+    {
+        // This would require cache prefix-based deletion
+        // Implementation depends on cache driver capabilities
+    }
+
+    /**
+     * Increment usage count for an index
+     */
+    private function incrementUsage(
+        IndexName $indexName,
+        string $tableName,
+        int $rowsExamined,
+        int $rowsReturned
+    ): void {
+        $cacheKey = $this->getCacheKey($indexName, $tableName);
+        $cached = $this->cache->get($cacheKey);
+
+        $data = $cached ? $cached->value : $this->initializeUsageData();
+
+        $data['usage_count']++;
+        $data['scan_count']++;
+        $data['rows_examined'] += $rowsExamined;
+        $data['rows_returned'] += $rowsReturned;
+        $data['last_used'] = (new DateTimeImmutable())->format('Y-m-d H:i:s');
+
+        $cacheItem = CacheItem::forSetting(
+            key: $cacheKey,
+            value: $data,
+            ttl: Duration::fromDays(self::CACHE_TTL_DAYS)
+        );
+
+        $this->cache->set($cacheItem);
+    }
+
+    /**
+     * Initialize empty usage data structure
+     */
+    private function initializeUsageData(): array
+    {
+        $now = new DateTimeImmutable();
+
+        return [
+            'usage_count' => 0,
+            'scan_count' => 0,
+            'rows_examined' => 0,
+            'rows_returned' => 0,
+            'last_used' => $now->format('Y-m-d H:i:s'),
+            'created_at' => $now->format('Y-m-d H:i:s')
+        ];
+    }
+
+    /**
+     * Calculate index selectivity (0.0 = all rows, 1.0 = unique rows)
+     */
+    private function calculateSelectivity(array $data): float
+    {
+        $rowsExamined = $data['rows_examined'] ?? 0;
+        $rowsReturned = $data['rows_returned'] ?? 0;
+
+        if ($rowsExamined === 0) {
+            return 1.0;
+        }
+
+        return 1.0 - ($rowsReturned / $rowsExamined);
+    }
+
+    /**
+     * Estimate rows returned from EXPLAIN analysis
+     */
+    private function estimateRowsReturned(array $analysis): int
+    {
+        // For now, assume 10% of examined rows are returned
+        // This is a rough estimate; actual tracking would need query result counting
+        return (int) ($analysis['rows_examined'] * 0.1);
+    }
+
+    /**
+     * Generate cache key for index usage data
+     */
+    private function getCacheKey(IndexName $indexName, string $tableName): CacheKey
+    {
+        return CacheKey::fromString(
+            self::CACHE_PREFIX . "{$tableName}_{$indexName->toString()}"
+        );
+    }
+}

src/Framework/Database/Indexing/UnusedIndexDetector.php

@@ -0,0 +1,279 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Database\Indexing;
+
+use App\Framework\Database\Indexing\ValueObjects\IndexName;
+use App\Framework\Database\Indexing\ValueObjects\IndexUsageMetrics;
+
+/**
+ * Detects unused or rarely used indexes that can be removed
+ *
+ * Helps identify indexes that waste storage and slow down writes
+ */
+final readonly class UnusedIndexDetector
+{
+    public function __construct(
+        private IndexAnalyzer $analyzer,
+        private IndexUsageTracker $usageTracker
+    ) {}
+
+    /**
+     * Find all unused indexes on a table
+     *
+     * @param int $daysThreshold Number of days without usage to consider unused
+     * @return array<array{
+     *     index_name: string,
+     *     table_name: string,
+     *     columns: array<string>,
+     *     last_used_days_ago: int,
+     *     can_be_dropped: bool,
+     *     reason: string
+     * }>
+     */
+    public function findUnusedIndexes(string $tableName, int $daysThreshold = 30): array
+    {
+        $indexes = $this->analyzer->getTableIndexes($tableName);
+        $unusedIndexes = [];
+
+        foreach ($indexes as $index) {
+            // Never suggest dropping PRIMARY or UNIQUE indexes
+            if ($index['is_primary'] || $index['is_unique']) {
+                continue;
+            }
+
+            $indexName = new IndexName($index['name']);
+            $usage = $this->usageTracker->getUsageMetrics($indexName, $tableName);
+
+            if (!$usage || $usage->isUnused($daysThreshold)) {
+                $daysSinceLastUse = $usage ? $usage->getDaysSinceLastUse() : PHP_INT_MAX;
+
+                $unusedIndexes[] = [
+                    'index_name' => $index['name'],
+                    'table_name' => $tableName,
+                    'columns' => $index['columns'],
+                    'last_used_days_ago' => $daysSinceLastUse,
+                    'can_be_dropped' => true,
+                    'reason' => $this->determineUnusedReason($usage, $daysThreshold)
+                ];
+            }
+        }
+
+        return $unusedIndexes;
+    }
+
+    /**
+     * Find duplicate indexes (indexes with identical column coverage)
+     *
+     * @return array<array{
+     *     duplicate_of: string,
+     *     index_name: string,
+     *     table_name: string,
+     *     columns: array<string>,
+     *     can_be_dropped: bool,
+     *     reason: string
+     * }>
+     */
+    public function findDuplicateIndexes(string $tableName): array
+    {
+        $indexes = $this->analyzer->getTableIndexes($tableName);
+        $duplicates = [];
+        $seen = [];
+
+        foreach ($indexes as $index) {
+            $columnKey = implode(',', $index['columns']);
+
+            if (isset($seen[$columnKey])) {
+                // This index duplicates an earlier one
+                $original = $seen[$columnKey];
+
+                // Don't suggest dropping PRIMARY or UNIQUE indexes
+                if ($index['is_primary'] || $index['is_unique']) {
+                    continue;
+                }
+
+                $duplicates[] = [
+                    'duplicate_of' => $original['name'],
+                    'index_name' => $index['name'],
+                    'table_name' => $tableName,
+                    'columns' => $index['columns'],
+                    'can_be_dropped' => true,
+                    'reason' => "Duplicate of index '{$original['name']}' on same columns"
+                ];
+            } else {
+                $seen[$columnKey] = $index;
+            }
+        }
+
+        return $duplicates;
+    }
+
+    /**
+     * Find redundant indexes (where one index is a prefix of another)
+     *
+     * Example: idx_user_email is redundant if idx_user_email_status exists
+     *
+     * @return array<array{
+     *     redundant_index: string,
+     *     covered_by: string,
+     *     table_name: string,
+     *     columns: array<string>,
+     *     can_be_dropped: bool,
+     *     reason: string
+     * }>
+     */
+    public function findRedundantIndexes(string $tableName): array
+    {
+        $indexes = $this->analyzer->getTableIndexes($tableName);
+        $redundant = [];
+
+        foreach ($indexes as $i => $index1) {
+            foreach ($indexes as $j => $index2) {
+                if ($i === $j) {
+                    continue;
+                }
+
+                // Check if index1 is a prefix of index2
+                if ($this->isPrefix($index1['columns'], $index2['columns'])) {
+                    // Don't suggest dropping PRIMARY or UNIQUE indexes
+                    if ($index1['is_primary'] || $index1['is_unique']) {
+                        continue;
+                    }
+
+                    $redundant[] = [
+                        'redundant_index' => $index1['name'],
+                        'covered_by' => $index2['name'],
+                        'table_name' => $tableName,
+                        'columns' => $index1['columns'],
+                        'can_be_dropped' => true,
+                        'reason' => "Columns are prefix of index '{$index2['name']}'"
+                    ];
+                    break; // Only report once per redundant index
+                }
+            }
+        }
+
+        return $redundant;
+    }
+
+    /**
+     * Get comprehensive unused index report for a table
+     *
+     * @return array{
+     *     unused: array,
+     *     duplicates: array,
+     *     redundant: array,
+     *     total_removable: int,
+     *     estimated_space_savings: string
+     * }
+     */
+    public function getUnusedIndexReport(string $tableName, int $daysThreshold = 30): array
+    {
+        $unused = $this->findUnusedIndexes($tableName, $daysThreshold);
+        $duplicates = $this->findDuplicateIndexes($tableName);
+        $redundant = $this->findRedundantIndexes($tableName);
+
+        $totalRemovable = count($unused) + count($duplicates) + count($redundant);
+
+        return [
+            'unused' => $unused,
+            'duplicates' => $duplicates,
+            'redundant' => $redundant,
+            'total_removable' => $totalRemovable,
+            'estimated_space_savings' => $this->estimateSpaceSavings($totalRemovable)
+        ];
+    }
+
+    /**
+     * Generate DROP INDEX statements for unused indexes
+     *
+     * @return array<string> SQL statements to drop unused indexes
+     */
+    public function generateDropStatements(string $tableName, int $daysThreshold = 30): array
+    {
+        $report = $this->getUnusedIndexReport($tableName, $daysThreshold);
+        $statements = [];
+
+        foreach ($report['unused'] as $index) {
+            if ($index['can_be_dropped']) {
+                $statements[] = "DROP INDEX {$index['index_name']} ON {$tableName};";
+            }
+        }
+
+        foreach ($report['duplicates'] as $index) {
+            if ($index['can_be_dropped']) {
+                $statements[] = "DROP INDEX {$index['index_name']} ON {$tableName};";
+            }
+        }
+
+        foreach ($report['redundant'] as $index) {
+            if ($index['can_be_dropped']) {
+                $statements[] = "DROP INDEX {$index['redundant_index']} ON {$tableName};";
+            }
+        }
+
+        return $statements;
+    }
+
+    /**
+     * Determine reason for marking index as unused
+     */
+    private function determineUnusedReason(?IndexUsageMetrics $usage, int $daysThreshold): string
+    {
+        if (!$usage) {
+            return 'Index has never been tracked or used';
+        }
+
+        if (!$usage->isUsed()) {
+            return 'Index has never been used since tracking started';
+        }
+
+        $daysSinceLastUse = $usage->getDaysSinceLastUse();
+
+        return "Index not used in last {$daysSinceLastUse} days (threshold: {$daysThreshold} days)";
+    }
+
+    /**
+     * Check if array1 is a prefix of array2
+     */
+    private function isPrefix(array $array1, array $array2): bool
+    {
+        if (count($array1) >= count($array2)) {
+            return false;
+        }
+
+        for ($i = 0; $i < count($array1); $i++) {
+            if ($array1[$i] !== $array2[$i]) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Estimate space savings from dropping indexes
+     */
+    private function estimateSpaceSavings(int $indexCount): string
+    {
+        // Rough estimate: each index ~5-10% of table size
+        // This is a simplified estimate
+        if ($indexCount === 0) {
+            return '0 MB';
+        }
+
+        $estimatedMB = $indexCount * 5;
+
+        if ($estimatedMB < 1) {
+            return '< 1 MB';
+        }
+
+        if ($estimatedMB > 1024) {
+            $estimatedGB = round($estimatedMB / 1024, 2);
+            return "{$estimatedGB} GB";
+        }
+
+        return "{$estimatedMB} MB";
+    }
+}

src/Framework/Database/Indexing/ValueObjects/IndexName.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Database\Indexing\ValueObjects;
+
+/**
+ * Value Object representing a database index name
+ */
+final readonly class IndexName
+{
+    public function __construct(
+        public string $value
+    ) {
+        if (empty($value)) {
+            throw new \InvalidArgumentException('Index name cannot be empty');
+        }
+
+        if (strlen($value) > 64) {
+            throw new \InvalidArgumentException('Index name cannot exceed 64 characters');
+        }
+
+        // Validate index name format (alphanumeric + underscore)
+        if (!preg_match('/^[a-zA-Z0-9_]+$/', $value)) {
+            throw new \InvalidArgumentException(
+                'Index name must contain only alphanumeric characters and underscores'
+            );
+        }
+    }
+
+    public function toString(): string
+    {
+        return $this->value;
+    }
+
+    public function equals(self $other): bool
+    {
+        return $this->value === $other->value;
+    }
+
+    public function __toString(): string
+    {
+        return $this->value;
+    }
+}

src/Framework/Database/Indexing/ValueObjects/IndexRecommendation.php

@@ -0,0 +1,115 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Database\Indexing\ValueObjects;
+
+/**
+ * Value Object representing an index optimization recommendation
+ */
+final readonly class IndexRecommendation
+{
+    public function __construct(
+        public string $tableName,
+        public array $columns,
+        public IndexType $indexType,
+        public string $reason,
+        public RecommendationPriority $priority,
+        public float $estimatedSpeedup,
+        public int $affectedQueries,
+        public ?string $migrationSql = null
+    ) {
+        if (empty($columns)) {
+            throw new \InvalidArgumentException('Columns array cannot be empty');
+        }
+
+        if ($estimatedSpeedup < 1.0) {
+            throw new \InvalidArgumentException('Estimated speedup must be >= 1.0');
+        }
+
+        if ($affectedQueries < 0) {
+            throw new \InvalidArgumentException('Affected queries cannot be negative');
+        }
+    }
+
+    public function getIndexName(): IndexName
+    {
+        $columnsPart = implode('_', array_map(
+            fn(string $col) => strtolower($col),
+            $this->columns
+        ));
+
+        $name = "idx_{$this->tableName}_{$columnsPart}";
+
+        // Truncate if too long (max 64 chars)
+        if (strlen($name) > 64) {
+            $name = substr($name, 0, 61) . '_' . substr(md5($name), 0, 2);
+        }
+
+        return new IndexName($name);
+    }
+
+    public function getColumnsString(): string
+    {
+        return implode(', ', $this->columns);
+    }
+
+    public function isComposite(): bool
+    {
+        return count($this->columns) > 1;
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'table_name' => $this->tableName,
+            'columns' => $this->columns,
+            'index_name' => $this->getIndexName()->toString(),
+            'index_type' => $this->indexType->value,
+            'reason' => $this->reason,
+            'priority' => $this->priority->value,
+            'estimated_speedup' => $this->estimatedSpeedup,
+            'affected_queries' => $this->affectedQueries,
+            'is_composite' => $this->isComposite(),
+            'migration_sql' => $this->migrationSql
+        ];
+    }
+}
+
+/**
+ * Enum representing recommendation priority levels
+ */
+enum RecommendationPriority: string
+{
+    case CRITICAL = 'critical';  // >10x speedup or >100 affected queries
+    case HIGH = 'high';          // >5x speedup or >50 affected queries
+    case MEDIUM = 'medium';      // >2x speedup or >20 affected queries
+    case LOW = 'low';            // <2x speedup or <20 affected queries
+
+    public static function fromMetrics(float $speedup, int $affectedQueries): self
+    {
+        if ($speedup >= 10.0 || $affectedQueries >= 100) {
+            return self::CRITICAL;
+        }
+
+        if ($speedup >= 5.0 || $affectedQueries >= 50) {
+            return self::HIGH;
+        }
+
+        if ($speedup >= 2.0 || $affectedQueries >= 20) {
+            return self::MEDIUM;
+        }
+
+        return self::LOW;
+    }
+
+    public function getColor(): string
+    {
+        return match ($this) {
+            self::CRITICAL => 'red',
+            self::HIGH => 'orange',
+            self::MEDIUM => 'yellow',
+            self::LOW => 'green',
+        };
+    }
+}

src/Framework/Database/Indexing/ValueObjects/IndexType.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Database\Indexing\ValueObjects;
+
+/**
+ * Enum representing database index types
+ */
+enum IndexType: string
+{
+    case BTREE = 'BTREE';
+    case HASH = 'HASH';
+    case FULLTEXT = 'FULLTEXT';
+    case SPATIAL = 'SPATIAL';
+    case GIN = 'GIN';          // PostgreSQL Generalized Inverted Index
+    case GIST = 'GIST';        // PostgreSQL Generalized Search Tree
+    case BRIN = 'BRIN';        // PostgreSQL Block Range Index
+    case PRIMARY = 'PRIMARY';
+    case UNIQUE = 'UNIQUE';
+
+    public function isSupported(string $driver): bool
+    {
+        return match ($this) {
+            self::BTREE, self::PRIMARY, self::UNIQUE => true,
+            self::HASH => in_array($driver, ['mysql', 'pgsql']),
+            self::FULLTEXT => $driver === 'mysql',
+            self::SPATIAL => $driver === 'mysql',
+            self::GIN, self::GIST, self::BRIN => $driver === 'pgsql',
+        };
+    }
+
+    public function getDescription(): string
+    {
+        return match ($this) {
+            self::BTREE => 'Balanced tree index - good for range queries',
+            self::HASH => 'Hash index - optimal for equality comparisons',
+            self::FULLTEXT => 'Full-text search index',
+            self::SPATIAL => 'Spatial/geographic data index',
+            self::GIN => 'Generalized Inverted Index - for composite types',
+            self::GIST => 'Generalized Search Tree - for geometric data',
+            self::BRIN => 'Block Range Index - for very large tables',
+            self::PRIMARY => 'Primary key index',
+            self::UNIQUE => 'Unique constraint index',
+        };
+    }
+}

src/Framework/Database/Indexing/ValueObjects/IndexUsageMetrics.php

@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Database\Indexing\ValueObjects;
+
+use DateTimeImmutable;
+
+/**
+ * Value Object representing index usage statistics
+ */
+final readonly class IndexUsageMetrics
+{
+    public function __construct(
+        public IndexName $indexName,
+        public string $tableName,
+        public int $usageCount,
+        public int $scanCount,
+        public float $selectivity,
+        public int $rowsExamined,
+        public int $rowsReturned,
+        public DateTimeImmutable $lastUsed,
+        public DateTimeImmutable $createdAt
+    ) {
+        if ($usageCount < 0) {
+            throw new \InvalidArgumentException('Usage count cannot be negative');
+        }
+
+        if ($scanCount < 0) {
+            throw new \InvalidArgumentException('Scan count cannot be negative');
+        }
+
+        if ($selectivity < 0.0 || $selectivity > 1.0) {
+            throw new \InvalidArgumentException('Selectivity must be between 0.0 and 1.0');
+        }
+
+        if ($rowsExamined < 0) {
+            throw new \InvalidArgumentException('Rows examined cannot be negative');
+        }
+
+        if ($rowsReturned < 0) {
+            throw new \InvalidArgumentException('Rows returned cannot be negative');
+        }
+    }
+
+    public function isUsed(): bool
+    {
+        return $this->usageCount > 0;
+    }
+
+    public function getEfficiency(): float
+    {
+        if ($this->rowsExamined === 0) {
+            return 1.0;
+        }
+
+        return $this->rowsReturned / $this->rowsExamined;
+    }
+
+    public function getAverageScanSize(): float
+    {
+        if ($this->scanCount === 0) {
+            return 0.0;
+        }
+
+        return $this->rowsExamined / $this->scanCount;
+    }
+
+    public function getDaysSinceLastUse(): int
+    {
+        $now = new DateTimeImmutable();
+        $interval = $now->diff($this->lastUsed);
+
+        return (int) $interval->days;
+    }
+
+    public function getDaysSinceCreation(): int
+    {
+        $now = new DateTimeImmutable();
+        $interval = $now->diff($this->createdAt);
+
+        return (int) $interval->days;
+    }
+
+    public function isUnused(int $daysThreshold = 30): bool
+    {
+        return !$this->isUsed() || $this->getDaysSinceLastUse() > $daysThreshold;
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'index_name' => $this->indexName->toString(),
+            'table_name' => $this->tableName,
+            'usage_count' => $this->usageCount,
+            'scan_count' => $this->scanCount,
+            'selectivity' => $this->selectivity,
+            'rows_examined' => $this->rowsExamined,
+            'rows_returned' => $this->rowsReturned,
+            'efficiency' => $this->getEfficiency(),
+            'average_scan_size' => $this->getAverageScanSize(),
+            'last_used' => $this->lastUsed->format('Y-m-d H:i:s'),
+            'created_at' => $this->createdAt->format('Y-m-d H:i:s'),
+            'days_since_last_use' => $this->getDaysSinceLastUse(),
+            'days_since_creation' => $this->getDaysSinceCreation(),
+            'is_unused' => $this->isUnused()
+        ];
+    }
+}