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/Infrastructure/GeoIp/GeoIp.php

@@ -5,6 +5,8 @@ declare(strict_types=1);
 namespace App\Infrastructure\GeoIp;
 
 use App\Framework\Http\IpAddress;
+use App\Framework\Database\PdoConnection;
+use App\Framework\Core\ValueObjects\CountryCode;
 use PDO;
 
 final class GeoIp
@@ -19,8 +21,9 @@ final class GeoIp
     {
         $databasePath = $databasePath ?? __DIR__ . '/data/ip_country.sqlite';
         $this->database = $this->initializeDatabase($databasePath);
-        $this->ipRangeService = new IpRangeService($this->database);
-        $this->countryDataService = new CountryDataService($this->database);
+        $connection = new PdoConnection($this->database);
+        $this->ipRangeService = new IpRangeService($connection);
+        $this->countryDataService = new CountryDataService($connection);
     }
 
     /**
@@ -46,6 +49,22 @@ final class GeoIp
         return $this->getCountryForString($ipAddress->value);
     }
 
+    public function getCountryCode(IpAddress $ipAddress): CountryCode
+    {
+        if ($ipAddress->isPrivate()) {
+            // Return a default country code for private IPs (e.g., local development)
+            return CountryCode::fromString('XX'); // XX = Unknown/Private
+        }
+
+        $countryCodeString = $this->getCountryForString($ipAddress->value);
+
+        if ($countryCodeString === null) {
+            return CountryCode::fromString('XX'); // Unknown
+        }
+
+        return CountryCode::fromString($countryCodeString);
+    }
+
     public function getCountryInfo(string $ip): CountryInfo
     {
         $countryCode = $this->getCountryForString($ip);