T-04: Encapsulate geo_service module-level mutable state in GeoCache class

Create GeoCache class with all mutable state as instance attributes:
- _cache, _neg_cache, _dirty, _geoip_reader, _geoip_initialized, _cache_lock
- All public methods: lookup(), lookup_batch(), lookup_cached_only(), flush_dirty(), load_from_db(), clear(), etc.

Initialization & Dependency Injection:
- Instantiate GeoCache in startup.py and store on app.state.geo_cache
- Add get_geo_cache() dependency function in dependencies.py
- Inject into routes and tasks via FastAPI's dependency system

Backward Compatibility:
- Maintain module-level functions in geo_service.py as deprecated wrappers
- All old callers continue to work through _default_geo_cache instance
- Remove test-escape-hatch functions (clear_cache, clear_neg_cache moved to methods)

Background Tasks:
- Update geo_cache_flush.py and geo_re_resolve.py to receive GeoCache instance
- Tasks now operate on injected instance rather than module globals

Tests:
- Refactor test_geo_service.py with geo_cache fixture providing fresh instances
- Update patch paths to target GeoCache methods correctly
- Fix internal state assertions to access instance attributes

Documentation:
- Update Architekture.md to document GeoCache as managed stateful service
- Describe cache lifecycle (load on startup, flush periodically, re-resolve stale)
- Note process-local limitations for multi-worker deployments

Fixes violation of Single Responsibility Principle: module no longer owns both
lookup logic and cache lifecycle management. Cache is now a first-class
injectable service with transparent lifecycle.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

backend/app/tasks/geo_cache_flush.py

@@ -1,7 +1,7 @@
 """Geo cache flush background task.
 
 Registers an APScheduler job that periodically persists newly resolved IP
-geo entries from the in-memory ``_dirty`` set to the ``geo_cache`` table.
+geo entries from the in-memory dirty set to the ``geo_cache`` table.
 
 After Task 2 removed geo cache writes from GET requests, newly resolved IPs
 are only held in the in-memory cache until this task flushes them.  With the
@@ -15,7 +15,7 @@ from typing import TYPE_CHECKING
 
 import structlog
 
-from app.services import geo_service
+from app.services.geo_cache import GeoCache
 from app.tasks.db import task_db
 from app.utils.runtime_state import get_effective_settings
 
@@ -33,21 +33,23 @@ GEO_FLUSH_INTERVAL: int = 60
 JOB_ID: str = "geo_cache_flush"
 
 
-async def _run_flush_with_settings(settings: Settings) -> None:
-    """Flush the geo service dirty set to the application database.
+async def _run_flush_with_resources(geo_cache: GeoCache, settings: Settings) -> None:
+    """Flush the geo cache dirty set to the application database.
 
     Args:
+        geo_cache: The application's GeoCache instance.
         settings: The resolved application settings used for database access.
     """
     async with task_db(settings) as db:
-        count = await geo_service.flush_dirty(db)
+        count = await geo_cache.flush_dirty(db)
 
     if count > 0:
         log.debug("geo_cache_flush_ran", flushed=count)
 
 
 async def _run_flush(app: FastAPI) -> None:
-    await _run_flush_with_settings(get_effective_settings(app))
+    geo_cache: GeoCache = app.state.geo_cache
+    await _run_flush_with_resources(geo_cache, get_effective_settings(app))
 
 
 def register(app: FastAPI) -> None:
@@ -60,12 +62,13 @@ def register(app: FastAPI) -> None:
         app: The :class:`fastapi.FastAPI` application instance whose
             ``app.state.scheduler`` will receive the job.
     """
+    geo_cache: GeoCache = app.state.geo_cache
     settings = get_effective_settings(app)
     app.state.scheduler.add_job(
-        _run_flush_with_settings,
+        _run_flush_with_resources,
         trigger="interval",
         seconds=GEO_FLUSH_INTERVAL,
-        kwargs={"settings": settings},
+        kwargs={"geo_cache": geo_cache, "settings": settings},
         id=JOB_ID,
         replace_existing=True,
     )

backend/app/tasks/geo_re_resolve.py

@@ -10,8 +10,8 @@ The task runs every 10 minutes.  On each invocation it:
 1. Queries all ``NULL``-country rows from ``geo_cache``.
 2. Clears the in-memory negative cache so those IPs are eligible for a fresh
    API attempt.
-3. Delegates to :func:`~app.services.geo_service.lookup_batch` which already
-   handles rate-limit throttling and retries.
+3. Delegates to :meth:`~app.services.geo_cache.GeoCache.lookup_batch` which
+   already handles rate-limit throttling and retries.
 4. Logs how many IPs were retried and how many resolved successfully.
 """
 
@@ -21,7 +21,7 @@ from typing import TYPE_CHECKING
 
 import structlog
 
-from app.services import geo_service
+from app.services.geo_cache import GeoCache
 from app.tasks.db import task_db
 from app.utils.runtime_state import get_effective_settings
 
@@ -40,16 +40,19 @@ GEO_RE_RESOLVE_INTERVAL: int = 600
 JOB_ID: str = "geo_re_resolve"
 
 
-async def _run_re_resolve_with_resources(settings: Settings, http_session: ClientSession) -> None:
+async def _run_re_resolve_with_resources(
+    geo_cache: GeoCache, settings: Settings, http_session: ClientSession
+) -> None:
     """Query NULL-country IPs from the database and re-resolve them.
 
     Args:
+        geo_cache: The application's GeoCache instance.
         settings: The resolved application settings used for database access.
         http_session: The shared aiohttp session used for external lookups.
     """
     async with task_db(settings) as db:
         # Fetch all IPs with NULL country_code from the persistent cache.
-        unresolved_ips = await geo_service.get_unresolved_ips(db)
+        unresolved_ips = await geo_cache.get_unresolved_ips(db)
 
         if not unresolved_ips:
             log.debug("geo_re_resolve_skip", reason="no_unresolved_ips")
@@ -58,11 +61,11 @@ async def _run_re_resolve_with_resources(settings: Settings, http_session: Clien
         log.info("geo_re_resolve_start", unresolved=len(unresolved_ips))
 
         # Clear the negative cache so these IPs are eligible for fresh API calls.
-        await geo_service.clear_neg_cache()
+        await geo_cache.clear_neg_cache()
 
         # lookup_batch handles throttling, retries, and persistence when db is
         # passed.  This is a background task so DB writes are allowed.
-        results = await geo_service.lookup_batch(unresolved_ips, http_session, db=db)
+        results = await geo_cache.lookup_batch(unresolved_ips, http_session, db=db)
 
     resolved_count: int = sum(
         1 for info in results.values() if info.country_code is not None
@@ -75,7 +78,10 @@ async def _run_re_resolve_with_resources(settings: Settings, http_session: Clien
 
 
 async def _run_re_resolve(app: FastAPI) -> None:
-    await _run_re_resolve_with_resources(get_effective_settings(app), app.state.http_session)
+    geo_cache: GeoCache = app.state.geo_cache
+    await _run_re_resolve_with_resources(
+        geo_cache, get_effective_settings(app), app.state.http_session
+    )
 
 
 def register(app: FastAPI) -> None:
@@ -91,12 +97,13 @@ def register(app: FastAPI) -> None:
         app: The :class:`fastapi.FastAPI` application instance whose
             ``app.state.scheduler`` will receive the job.
     """
+    geo_cache: GeoCache = app.state.geo_cache
     settings = get_effective_settings(app)
     app.state.scheduler.add_job(
         _run_re_resolve_with_resources,
         trigger="interval",
         seconds=GEO_RE_RESOLVE_INTERVAL,
-        kwargs={"settings": settings, "http_session": app.state.http_session},
+        kwargs={"geo_cache": geo_cache, "settings": settings, "http_session": app.state.http_session},
         id=JOB_ID,
         replace_existing=True,
     )