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

tests/Framework/Router/UrlGeneratorRouteEnumTest.php

@@ -0,0 +1,138 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Router\UrlGenerator;
+use App\Framework\Router\CompiledRoutes;
+use App\Framework\Router\WebRoutes;
+use App\Framework\Router\ApiRoutes;
+use App\Framework\Router\AdminRoutes;
+use App\Framework\Http\Request;
+
+describe('UrlGenerator with Route Enums', function () {
+    beforeEach(function () {
+        $this->mockRequest = mock(Request::class);
+        $this->mockCompiledRoutes = mock(CompiledRoutes::class);
+        $this->urlGenerator = new UrlGenerator($this->mockRequest, $this->mockCompiledRoutes);
+    });
+
+    describe('route generation with enums', function () {
+        it('generates URLs using WebRoutes enum', function () {
+            $mockRoute = (object) ['path' => '/'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('home')
+                ->andReturn($mockRoute);
+
+            $result = $this->urlGenerator->route(WebRoutes::HOME);
+
+            expect($result)->toBe('/');
+        });
+
+        it('generates URLs using ApiRoutes enum', function () {
+            $mockRoute = (object) ['path' => '/api/users'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('api_users_list')
+                ->andReturn($mockRoute);
+
+            $result = $this->urlGenerator->route(ApiRoutes::USERS_LIST);
+
+            expect($result)->toBe('/api/users');
+        });
+
+        it('generates URLs using AdminRoutes enum', function () {
+            $mockRoute = (object) ['path' => '/admin'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('admin.dashboard')
+                ->andReturn($mockRoute);
+
+            $result = $this->urlGenerator->route(AdminRoutes::DASHBOARD);
+
+            expect($result)->toBe('/admin');
+        });
+
+        it('generates URLs with parameters using enum', function () {
+            $mockRoute = (object) ['path' => '/api/users/{id}'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('api_users_show')
+                ->andReturn($mockRoute);
+
+            $result = $this->urlGenerator->route(ApiRoutes::USERS_SHOW, ['id' => 123]);
+
+            expect($result)->toBe('/api/users/123');
+        });
+    });
+
+    describe('backward compatibility', function () {
+        it('still works with string route names', function () {
+            $mockRoute = (object) ['path' => '/legacy'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('legacy_route')
+                ->andReturn($mockRoute);
+
+            $result = $this->urlGenerator->route('legacy_route');
+
+            expect($result)->toBe('/legacy');
+        });
+    });
+
+    describe('absolute URL generation', function () {
+        it('generates absolute URLs using enums', function () {
+            $mockRoute = (object) ['path' => '/'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('home')
+                ->andReturn($mockRoute);
+
+            $this->mockRequest->server = mock();
+            $this->mockRequest->server->shouldReceive('isHttps')->andReturn(true);
+            $this->mockRequest->server->shouldReceive('getHttpHost')->andReturn('example.com');
+
+            $result = $this->urlGenerator->absoluteRoute(WebRoutes::HOME);
+
+            expect($result)->toBe('https://example.com/');
+        });
+    });
+
+    describe('current route checking', function () {
+        it('checks current route using enum', function () {
+            $mockRoute = (object) ['path' => '/'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('home')
+                ->andReturn($mockRoute);
+
+            $this->mockRequest->path = '/';
+
+            $result = $this->urlGenerator->isCurrentRoute(WebRoutes::HOME);
+
+            expect($result)->toBeTrue();
+        });
+
+        it('returns false for non-matching enum route', function () {
+            $mockRoute = (object) ['path' => '/admin'];
+
+            $this->mockCompiledRoutes->shouldReceive('getNamedRoute')
+                ->once()
+                ->with('admin.dashboard')
+                ->andReturn($mockRoute);
+
+            $this->mockRequest->path = '/';
+
+            $result = $this->urlGenerator->isCurrentRoute(AdminRoutes::DASHBOARD);
+
+            expect($result)->toBeFalse();
+        });
+    });
+});