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/Framework/Queue/Contracts/DeadLetterQueueInterface.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Queue\Contracts;
+
+use App\Framework\Queue\Entities\DeadLetterJob;
+use App\Framework\Queue\ValueObjects\DeadLetterQueueName;
+use App\Framework\Queue\ValueObjects\QueueName;
+
+/**
+ * Interface for Dead Letter Queue operations
+ */
+interface DeadLetterQueueInterface
+{
+    /**
+     * Add a failed job to the dead letter queue
+     */
+    public function addFailedJob(DeadLetterJob $deadLetterJob): void;
+
+    /**
+     * Get all jobs from a dead letter queue
+     *
+     * @return DeadLetterJob[]
+     */
+    public function getJobs(DeadLetterQueueName $deadLetterQueueName, int $limit = 100): array;
+
+    /**
+     * Get jobs from dead letter queue by original queue
+     *
+     * @return DeadLetterJob[]
+     */
+    public function getJobsByOriginalQueue(QueueName $originalQueue, int $limit = 100): array;
+
+    /**
+     * Retry a job from the dead letter queue
+     * Moves it back to the original queue and increments retry count
+     */
+    public function retryJob(string $deadLetterJobId): bool;
+
+    /**
+     * Permanently delete a job from the dead letter queue
+     */
+    public function deleteJob(string $deadLetterJobId): bool;
+
+    /**
+     * Retry all jobs in a dead letter queue
+     * Returns the number of jobs successfully retried
+     */
+    public function retryAllJobs(DeadLetterQueueName $deadLetterQueueName): int;
+
+    /**
+     * Clear all jobs from a dead letter queue
+     * Returns the number of jobs deleted
+     */
+    public function clearQueue(DeadLetterQueueName $deadLetterQueueName): int;
+
+    /**
+     * Get statistics for a dead letter queue
+     */
+    public function getQueueStats(DeadLetterQueueName $deadLetterQueueName): array;
+
+    /**
+     * Get all dead letter queue names
+     *
+     * @return DeadLetterQueueName[]
+     */
+    public function getAvailableQueues(): array;
+}

src/Framework/Queue/Contracts/JobBatchManagerInterface.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Queue\Contracts;
+
+use App\Framework\Queue\ValueObjects\JobBatch;
+use App\Framework\Queue\ValueObjects\JobBatchStatus;
+
+/**
+ * Interface for managing job batches
+ */
+interface JobBatchManagerInterface
+{
+    /**
+     * Create a new job batch
+     */
+    public function createBatch(string $name, array $jobIds, array $options = []): JobBatch;
+
+    /**
+     * Get a batch by ID
+     */
+    public function getBatch(string $batchId): ?JobBatch;
+
+    /**
+     * Update batch progress when a job completes
+     */
+    public function recordJobCompleted(string $batchId, string $jobId): void;
+
+    /**
+     * Update batch progress when a job fails
+     */
+    public function recordJobFailed(string $batchId, string $jobId): void;
+
+    /**
+     * Cancel a batch
+     */
+    public function cancelBatch(string $batchId): bool;
+
+    /**
+     * Get batches by status
+     */
+    public function getBatchesByStatus(JobBatchStatus $status, int $limit = 50): array;
+
+    /**
+     * Get batch statistics
+     */
+    public function getBatchStats(): array;
+
+    /**
+     * Clean up old batches
+     */
+    public function cleanupOldBatches(int $olderThanDays = 30): int;
+
+    /**
+     * Get batch progress
+     */
+    public function getBatchProgress(string $batchId): array;
+}

src/Framework/Queue/Contracts/JobChainManagerInterface.php

@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Queue\Contracts;
+
+use App\Framework\Queue\ValueObjects\JobChain;
+use App\Framework\Queue\Entities\JobChainEntry;
+
+/**
+ * Interface for managing job chains
+ */
+interface JobChainManagerInterface
+{
+    /**
+     * Create a new job chain
+     */
+    public function createChain(JobChain $jobChain): void;
+
+    /**
+     * Get a job chain by its ID
+     */
+    public function getChain(string $chainId): ?JobChainEntry;
+
+    /**
+     * Update an existing job chain
+     */
+    public function updateChain(JobChain $jobChain): void;
+
+    /**
+     * Delete a job chain
+     */
+    public function deleteChain(string $chainId): void;
+
+    /**
+     * Start execution of a job chain
+     */
+    public function startChain(string $chainId): void;
+
+    /**
+     * Get all chains for a specific job
+     */
+    public function getChainsForJob(string $jobId): array;
+
+    /**
+     * Get all active (running) chains
+     */
+    public function getActiveChains(): array;
+
+    /**
+     * Get all pending chains
+     */
+    public function getPendingChains(): array;
+
+    /**
+     * Mark a chain as completed
+     */
+    public function markChainAsCompleted(string $chainId): void;
+
+    /**
+     * Mark a chain as failed
+     */
+    public function markChainAsFailed(string $chainId): void;
+
+    /**
+     * Get the next job in a chain to execute
+     */
+    public function getNextJobInChain(string $chainId, ?string $currentJobId = null): ?string;
+
+    /**
+     * Check if a chain is complete
+     */
+    public function isChainComplete(string $chainId): bool;
+
+    /**
+     * Handle job completion within a chain
+     */
+    public function handleJobCompletion(string $jobId, bool $successful = true): void;
+
+    /**
+     * Get chain execution status and progress
+     */
+    public function getChainProgress(string $chainId): array;
+
+    /**
+     * Clean up old completed chains
+     */
+    public function cleanupOldChains(int $olderThanDays = 30): int;
+}

src/Framework/Queue/Contracts/JobDependencyManagerInterface.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Queue\Contracts;
+
+use App\Framework\Queue\ValueObjects\JobDependency;
+use App\Framework\Queue\Entities\JobDependencyEntry;
+
+/**
+ * Interface for managing job dependencies
+ */
+interface JobDependencyManagerInterface
+{
+    /**
+     * Add a dependency between two jobs
+     */
+    public function addDependency(JobDependency $dependency): void;
+
+    /**
+     * Remove a dependency
+     */
+    public function removeDependency(string $dependentJobId, string $dependsOnJobId): void;
+
+    /**
+     * Get all dependencies for a job (jobs this job depends on)
+     */
+    public function getDependencies(string $jobId): array;
+
+    /**
+     * Get all dependents for a job (jobs that depend on this job)
+     */
+    public function getDependents(string $jobId): array;
+
+    /**
+     * Check if a job has any unsatisfied dependencies
+     */
+    public function hasUnsatisfiedDependencies(string $jobId): bool;
+
+    /**
+     * Get unsatisfied dependencies for a job
+     *
+     * @return JobDependencyEntry[]
+     */
+    public function getUnsatisfiedDependencies(string $jobId): array;
+
+    /**
+     * Mark a dependency as satisfied
+     */
+    public function markDependencyAsSatisfied(string $dependentJobId, string $dependsOnJobId): void;
+
+    /**
+     * Check if a job can be executed (all dependencies satisfied)
+     */
+    public function canJobBeExecuted(string $jobId): bool;
+
+    /**
+     * Get jobs that are ready to be executed (no unsatisfied dependencies)
+     */
+    public function getReadyJobs(): array;
+
+    /**
+     * Resolve dependencies when a job completes
+     */
+    public function resolveJobCompletion(string $jobId, bool $successful = true): array;
+
+    /**
+     * Get dependency chain for a job (all jobs it transitively depends on)
+     */
+    public function getDependencyChain(string $jobId): array;
+
+    /**
+     * Check for circular dependencies
+     */
+    public function hasCircularDependencies(string $jobId): bool;
+
+    /**
+     * Clean up old satisfied dependencies
+     */
+    public function cleanupOldDependencies(int $olderThanDays = 30): int;
+}

src/Framework/Queue/Contracts/JobProgressTrackerInterface.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Queue\Contracts;
+
+use App\Framework\Queue\Entities\JobProgressEntry;
+use App\Framework\Queue\ValueObjects\JobProgress;
+use App\Framework\Queue\ValueObjects\ProgressStep;
+
+/**
+ * Interface for tracking job progress
+ */
+interface JobProgressTrackerInterface
+{
+    /**
+     * Update job progress
+     */
+    public function updateProgress(string $jobId, JobProgress $progress, ?string $stepName = null): void;
+
+    /**
+     * Mark a step as completed
+     */
+    public function completeStep(string $jobId, ProgressStep $step): void;
+
+    /**
+     * Get current progress for a job
+     */
+    public function getCurrentProgress(string $jobId): ?JobProgress;
+
+    /**
+     * Get all progress entries for a job
+     *
+     * @return JobProgressEntry[]
+     */
+    public function getProgressHistory(string $jobId): array;
+
+    /**
+     * Get latest progress entry for a job
+     */
+    public function getLatestProgressEntry(string $jobId): ?JobProgressEntry;
+
+    /**
+     * Mark job as completed
+     */
+    public function markJobCompleted(string $jobId, string $message = 'Job completed successfully'): void;
+
+    /**
+     * Mark job as failed
+     */
+    public function markJobFailed(string $jobId, string $message = 'Job failed', ?\Throwable $exception = null): void;
+
+    /**
+     * Get progress for multiple jobs
+     *
+     * @param string[] $jobIds
+     * @return array<string, JobProgress> Job ID => Progress
+     */
+    public function getProgressForJobs(array $jobIds): array;
+
+    /**
+     * Clean up old progress entries
+     * Returns number of deleted entries
+     */
+    public function cleanupOldEntries(int $olderThanDays = 30): int;
+
+    /**
+     * Get jobs with progress above a certain percentage
+     *
+     * @return JobProgressEntry[]
+     */
+    public function getJobsAboveProgress(float $minPercentage): array;
+
+    /**
+     * Get recently updated jobs
+     *
+     * @return JobProgressEntry[]
+     */
+    public function getRecentlyUpdatedJobs(int $limitMinutes = 60, int $limit = 100): array;
+}