feat - ip map

.gitignore

@@ -49,6 +49,7 @@ coverage.xml
 *.py.cover
 .hypothesis/
 .pytest_cache/
+.pytest_tmp/
 cover/
 
 # Translations

src/leaderboard_analytics/ui.py

@@ -8,6 +8,7 @@ from typing import Any
 import gradio as gr
 import pandas as pd
 import plotly.express as px
+import plotly.graph_objects as go
 
 from leaderboard_analytics.schemas import Granularity, QueryFilters
 from leaderboard_analytics.services import AnalyticsService
@@ -40,7 +41,9 @@ def _empty_plot(title: str):
 
 
 def _empty_map(title: str):
-    return px.choropleth(title=title)
+    figure = go.Figure()
+    _style_visitor_location_map(figure, title)
+    return figure
 
 
 def _query_range_text(filters: QueryFilters) -> str:
@@ -74,7 +77,9 @@ def _visitor_location_top_table(visitor_locations: pd.DataFrame) -> pd.DataFrame
 
 
 def _visitor_location_debug_text(
-    visitor_locations: pd.DataFrame, geoip_debug: dict[str, object]
+    visitor_locations: pd.DataFrame,
+    geoip_debug: dict[str, object],
+    ip_debug: dict[str, object] | None = None,
 ) -> str:
     if visitor_locations.empty:
         total_pv = 0
@@ -96,6 +101,16 @@ def _visitor_location_debug_text(
     loaded = "yes" if geoip_debug.get("reader_loaded") else "no"
     attempted = "yes" if geoip_debug.get("load_attempted") else "no"
     path = geoip_debug.get("database_path") or "(not configured)"
+    ip_debug = ip_debug or {}
+    global_ips = int(ip_debug.get("global_ips", 0))
+    global_pv = int(ip_debug.get("global_ip_pv", 0))
+    private_ips = int(ip_debug.get("private_ips", 0))
+    private_pv = int(ip_debug.get("private_ip_pv", 0))
+    loopback_ips = int(ip_debug.get("loopback_ips", 0))
+    loopback_pv = int(ip_debug.get("loopback_ip_pv", 0))
+    invalid_ips = int(ip_debug.get("invalid_ips", 0))
+    invalid_pv = int(ip_debug.get("invalid_ip_pv", 0))
+    buckets = ip_debug.get("top_ip_pv_buckets", {})
 
     return (
         f"GeoIP DB: configured={configured}, exists={exists}, loaded={loaded}, "
@@ -103,10 +118,106 @@ def _visitor_location_debug_text(
         f"GeoIP path: `{path}`  \n"
         f"Total location PV: {total_pv} | Users/IPs: {total_users} | "
         f"Mapped regions: {mapped_regions}  \n"
-        f"Unknown PV: {unknown_pv} | Unknown users/IPs: {unknown_users}"
+        f"Unknown PV: {unknown_pv} | Unknown users/IPs: {unknown_users}  \n"
+        f"Public IPs: {global_ips} ({global_pv} PV) | Private IPs: {private_ips} "
+        f"({private_pv} PV)  \n"
+        f"Loopback IPs: {loopback_ips} ({loopback_pv} PV) | Invalid IPs: {invalid_ips} "
+        f"({invalid_pv} PV)  \n"
+        f"PV/IP buckets: {buckets}"
     )
 
 
+def _style_visitor_location_map(figure: go.Figure, title: str) -> None:
+    figure.update_geos(
+        projection_type="mercator",
+        showframe=False,
+        showcoastlines=True,
+        coastlinecolor="#cfd6df",
+        coastlinewidth=0.6,
+        showcountries=True,
+        countrycolor="#cfd6df",
+        countrywidth=0.7,
+        showland=True,
+        landcolor="#eef2f7",
+        showocean=True,
+        oceancolor="#f8fafc",
+        showlakes=True,
+        lakecolor="#f8fafc",
+        bgcolor="#ffffff",
+        lataxis_range=[-55, 75],
+        lonaxis_range=[-180, 180],
+    )
+    figure.update_layout(
+        title={"text": title, "x": 0.02, "xanchor": "left"},
+        height=560,
+        paper_bgcolor="#ffffff",
+        plot_bgcolor="#ffffff",
+        font={"color": "#1f2937"},
+        margin={"l": 0, "r": 0, "t": 52, "b": 0},
+        showlegend=False,
+        hoverlabel={
+            "bgcolor": "#ffffff",
+            "bordercolor": "#3b82f6",
+            "font_color": "#111827",
+        },
+    )
+
+
+def _visitor_location_map(visitor_locations: pd.DataFrame, range_text: str) -> go.Figure:
+    map_df = (
+        visitor_locations[visitor_locations["country_code"] != "Unknown"].copy()
+        if not visitor_locations.empty
+        else visitor_locations.copy()
+    )
+    if map_df.empty:
+        return _empty_map(f"Visitor locations by country (no mapped data for {range_text})")
+
+    max_pv = max(int(map_df["pv"].max()), 1)
+    size_ref = 2.0 * max_pv / (52**2)
+    figure = go.Figure(
+        go.Scattergeo(
+            locationmode="country names",
+            locations=map_df["country_name"],
+            mode="markers",
+            text=map_df["country_name"],
+            customdata=map_df[["country_code", "pv", "ip_count"]],
+            hovertemplate=(
+                "<b>%{text}</b><br>"
+                "Country code: %{customdata[0]}<br>"
+                "PV: %{customdata[1]:,}<br>"
+                "Users/IPs: %{customdata[2]:,}<extra></extra>"
+            ),
+            marker={
+                "size": map_df["pv"],
+                "sizemode": "area",
+                "sizeref": size_ref,
+                "sizemin": 8,
+                "color": "rgba(59, 130, 246, 0.55)",
+                "line": {"color": "rgba(37, 99, 235, 0.92)", "width": 1.2},
+            },
+        )
+    )
+    _style_visitor_location_map(figure, "Visitor locations by country")
+    figure.add_annotation(
+        x=0.02,
+        y=0.08,
+        xref="paper",
+        yref="paper",
+        text=(
+            f"Mapped regions: {len(map_df)}<br>"
+            f"Mapped PV: {int(map_df['pv'].sum()):,}<br>"
+            f"Users/IPs: {int(map_df['ip_count'].sum()):,}"
+        ),
+        showarrow=False,
+        align="left",
+        bgcolor="rgba(255, 255, 255, 0.88)",
+        bordercolor="rgba(148, 163, 184, 0.55)",
+        borderwidth=1,
+        font={"color": "#1f2937", "size": 12},
+    )
+    return figure
+
+
 def build_dashboard(service: AnalyticsService) -> gr.Blocks:
     default_end = datetime.now(tz=UTC)
     default_start = (default_end - timedelta(days=7)).replace(microsecond=0)
@@ -153,11 +264,12 @@ def build_dashboard(service: AnalyticsService) -> gr.Blocks:
             filter_df = service.get_filter_distribution(filters)
             funnel_df = service.get_funnel(filters)
             visitors_df = service.get_new_vs_returning(filters)
-            visitor_locations_df = service.get_visitor_locations(filters)
+            visitor_locations_df, ip_debug = service.get_visitor_location_details(filters)
             visitor_locations_top_df = _visitor_location_top_table(visitor_locations_df)
             visitor_locations_debug = _visitor_location_debug_text(
                 visitor_locations_df,
                 service.get_geoip_debug_info(),
+                ip_debug,
             )
 
             range_text = _query_range_text(filters)
@@ -210,28 +322,7 @@ def build_dashboard(service: AnalyticsService) -> gr.Blocks:
                 if not visitors_df.empty
                 else px.bar(title=f"New vs returning visitors (no data for {range_text})")
             )
-            map_df = (
-                visitor_locations_df[visitor_locations_df["country_code"] != "Unknown"]
-                if not visitor_locations_df.empty
-                else visitor_locations_df
-            )
-            visitor_locations_plot = (
-                px.choropleth(
-                    map_df,
-                    locations="country_code",
-                    color="pv",
-                    hover_name="country_name",
-                    hover_data={"country_code": True, "pv": True, "ip_count": True},
-                    color_continuous_scale="Blues",
-                    title="Visitor locations by country",
-                )
-                if not map_df.empty
-                else _empty_map(f"Visitor locations by country (no data for {range_text})")
-            )
-            visitor_locations_plot.update_layout(
-                height=520,
-                margin={"l": 0, "r": 0, "t": 48, "b": 0},
-            )
+            visitor_locations_plot = _visitor_location_map(visitor_locations_df, range_text)
             csv_archive = _write_csv_archive(
                 {
                     "overview": overview_df,