feat: add hidden debug dashboard

Add /debug route with comprehensive status overview:
- Spec/implementation counts and coverage stats
- Library coverage cards (impl count, avg/min/max scores)
- Problem areas (low scores, missing previews/tags, oldest specs)
- System health (database status, API response time)
- Filterable table (search, incomplete, low scores, missing library)
- Sortable by ID, title, avg score, updated date

Backend: GET /debug/status endpoint with full statistics
Frontend: DebugPage with MUI components
Access: Triple-click on logo or direct /debug URL

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: MarkusNeusinger

api/main.py

@@ -23,6 +23,7 @@
     pyplots_exception_handler,
 )
 from api.routers import (  # noqa: E402
+    debug_router,
     download_router,
     health_router,
     libraries_router,
@@ -132,6 +133,7 @@ async def add_cache_headers(request: Request, call_next):
 app.include_router(seo_router)
 app.include_router(og_images_router)
 app.include_router(proxy_router)
+app.include_router(debug_router)
 
 
 if __name__ == "__main__":

api/routers/__init__.py

@@ -1,5 +1,6 @@
 """API routers."""
 
+from api.routers.debug import router as debug_router
 from api.routers.download import router as download_router
 from api.routers.health import router as health_router
 from api.routers.libraries import router as libraries_router
@@ -12,6 +13,7 @@
 
 
 __all__ = [
+    "debug_router",
     "download_router",
     "health_router",
     "libraries_router",

api/routers/debug.py

@@ -0,0 +1,281 @@
+"""Debug endpoints for internal monitoring."""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends, Request
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api.dependencies import require_db
+from core.constants import SUPPORTED_LIBRARIES
+from core.database import SpecRepository
+
+
+router = APIRouter(prefix="/debug", tags=["debug"])
+
+
+# ============================================================================
+# Response Models
+# ============================================================================
+
+
+class SpecStatusItem(BaseModel):
+    """Status for a single specification with library scores."""
+
+    id: str
+    title: str
+    updated: str | None
+    avg_score: float | None = None
+    # Library scores - None means no implementation
+    altair: float | None = None
+    bokeh: float | None = None
+    highcharts: float | None = None
+    letsplot: float | None = None
+    matplotlib: float | None = None
+    plotly: float | None = None
+    plotnine: float | None = None
+    pygal: float | None = None
+    seaborn: float | None = None
+
+
+class LibraryStats(BaseModel):
+    """Statistics for a single library."""
+
+    id: str
+    name: str
+    impl_count: int
+    avg_score: float | None
+    min_score: float | None
+    max_score: float | None
+
+
+class ProblemSpec(BaseModel):
+    """A spec with issues."""
+
+    id: str
+    title: str
+    issue: str  # Description of the problem
+    value: str | None = None  # Optional value (e.g., score, date)
+
+
+class SystemHealth(BaseModel):
+    """System health information."""
+
+    database_connected: bool
+    api_response_time_ms: float
+    timestamp: str
+    total_specs_in_db: int
+    total_impls_in_db: int
+
+
+class DebugStatusResponse(BaseModel):
+    """Debug dashboard data."""
+
+    # Summary
+    total_specs: int
+    total_implementations: int
+    coverage_percent: float
+
+    # Library statistics
+    library_stats: list[LibraryStats]
+
+    # Problem areas
+    low_score_specs: list[ProblemSpec]  # Specs with avg score < 85
+    oldest_specs: list[ProblemSpec]  # 10 oldest specs
+    missing_preview_specs: list[ProblemSpec]  # Specs with missing GCS images
+    missing_tags_specs: list[ProblemSpec]  # Specs without tags
+
+    # System health
+    system: SystemHealth
+
+    # All specs for table
+    specs: list[SpecStatusItem]
+
+
+# ============================================================================
+# Endpoint
+# ============================================================================
+
+
+@router.get("/status", response_model=DebugStatusResponse)
+async def get_debug_status(request: Request, db: AsyncSession = Depends(require_db)) -> DebugStatusResponse:
+    """
+    Get comprehensive debug dashboard data.
+
+    Includes:
+    - All specs with quality scores per library
+    - Library statistics (avg/min/max scores, coverage)
+    - Problem specs (low scores, old, missing data)
+    - System health info
+    """
+    start_time = time.time()
+
+    repo = SpecRepository(db)
+    all_specs = await repo.get_all()
+
+    # ========================================================================
+    # Build specs list and collect statistics
+    # ========================================================================
+
+    specs_status: list[SpecStatusItem] = []
+    total_implementations = 0
+
+    # Library aggregates
+    library_scores: dict[str, list[float]] = {lib: [] for lib in SUPPORTED_LIBRARIES}
+    library_counts: dict[str, int] = dict.fromkeys(SUPPORTED_LIBRARIES, 0)  # type: ignore[arg-type]
+
+    # Problem tracking
+    missing_preview: list[ProblemSpec] = []
+    missing_tags: list[ProblemSpec] = []
+
+    for spec in all_specs:
+        # Build library score map for this spec
+        spec_scores: dict[str, float | None] = dict.fromkeys(SUPPORTED_LIBRARIES, None)
+        spec_score_values: list[float] = []
+
+        for impl in spec.impls:
+            lib_id = impl.library_id
+            score = impl.quality_score
+
+            spec_scores[lib_id] = score
+            total_implementations += 1
+            library_counts[lib_id] += 1
+
+            if score is not None:
+                library_scores[lib_id].append(score)
+                spec_score_values.append(score)
+
+            # Check for missing preview
+            if not impl.preview_url:
+                missing_preview.append(ProblemSpec(id=spec.id, title=spec.title, issue=f"Missing preview for {lib_id}"))
+
+        # Calculate average score for this spec
+        avg_score = sum(spec_score_values) / len(spec_score_values) if spec_score_values else None
+
+        # Find most recent update
+        timestamps = [spec.updated] if spec.updated else []
+        timestamps.extend(impl.updated for impl in spec.impls if impl.updated)
+        most_recent = max(timestamps) if timestamps else None
+
+        # Check for missing tags
+        if not spec.tags or not any(spec.tags.values()):
+            missing_tags.append(ProblemSpec(id=spec.id, title=spec.title, issue="No tags defined"))
+
+        specs_status.append(
+            SpecStatusItem(
+                id=spec.id,
+                title=spec.title,
+                updated=most_recent.isoformat() if most_recent else None,
+                avg_score=round(avg_score, 1) if avg_score else None,
+                altair=spec_scores.get("altair"),
+                bokeh=spec_scores.get("bokeh"),
+                highcharts=spec_scores.get("highcharts"),
+                letsplot=spec_scores.get("letsplot"),
+                matplotlib=spec_scores.get("matplotlib"),
+                plotly=spec_scores.get("plotly"),
+                plotnine=spec_scores.get("plotnine"),
+                pygal=spec_scores.get("pygal"),
+                seaborn=spec_scores.get("seaborn"),
+            )
+        )
+
+    # Sort by updated (most recent first)
+    specs_status.sort(key=lambda s: (s.updated or "", s.id), reverse=True)
+
+    # ========================================================================
+    # Library Statistics
+    # ========================================================================
+
+    library_names = {
+        "altair": "Altair",
+        "bokeh": "Bokeh",
+        "highcharts": "Highcharts",
+        "letsplot": "lets-plot",
+        "matplotlib": "Matplotlib",
+        "plotly": "Plotly",
+        "plotnine": "plotnine",
+        "pygal": "Pygal",
+        "seaborn": "Seaborn",
+    }
+
+    lib_stats: list[LibraryStats] = []
+    for lib_id in sorted(SUPPORTED_LIBRARIES):
+        scores = library_scores[lib_id]
+        lib_stats.append(
+            LibraryStats(
+                id=lib_id,
+                name=library_names.get(lib_id, lib_id),
+                impl_count=library_counts[lib_id],
+                avg_score=round(sum(scores) / len(scores), 1) if scores else None,
+                min_score=round(min(scores), 1) if scores else None,
+                max_score=round(max(scores), 1) if scores else None,
+            )
+        )
+
+    # Sort by impl_count descending
+    lib_stats.sort(key=lambda x: x.impl_count, reverse=True)
+
+    # ========================================================================
+    # Problem Specs
+    # ========================================================================
+
+    # Low score specs (avg < 85)
+    low_score_specs: list[ProblemSpec] = []
+    for spec in specs_status:
+        if spec.avg_score is not None and spec.avg_score < 85:
+            low_score_specs.append(
+                ProblemSpec(id=spec.id, title=spec.title, issue="Low average score", value=f"{spec.avg_score:.1f}")
+            )
+    low_score_specs.sort(key=lambda x: float(x.value or 0))  # Lowest first
+
+    # Oldest specs (by updated timestamp)
+    specs_by_age = sorted(specs_status, key=lambda s: s.updated or "")
+    oldest_specs: list[ProblemSpec] = []
+    for spec in specs_by_age[:10]:  # 10 oldest
+        if spec.updated:
+            try:
+                dt = datetime.fromisoformat(spec.updated.replace("Z", "+00:00"))
+                # Ensure dt is timezone-aware
+                if dt.tzinfo is None:
+                    dt = dt.replace(tzinfo=timezone.utc)
+                age_days = (datetime.now(timezone.utc) - dt).days
+                oldest_specs.append(
+                    ProblemSpec(id=spec.id, title=spec.title, issue="Old spec", value=f"{age_days} days ago")
+                )
+            except ValueError:
+                pass
+
+    # ========================================================================
+    # System Health
+    # ========================================================================
+
+    response_time_ms = (time.time() - start_time) * 1000
+    coverage = (total_implementations / (len(all_specs) * 9) * 100) if all_specs else 0
+
+    system_health = SystemHealth(
+        database_connected=True,
+        api_response_time_ms=round(response_time_ms, 2),
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        total_specs_in_db=len(all_specs),
+        total_impls_in_db=total_implementations,
+    )
+
+    # ========================================================================
+    # Return Response
+    # ========================================================================
+
+    return DebugStatusResponse(
+        total_specs=len(all_specs),
+        total_implementations=total_implementations,
+        coverage_percent=round(coverage, 1),
+        library_stats=lib_stats,
+        low_score_specs=low_score_specs[:20],  # Limit to 20
+        oldest_specs=oldest_specs,
+        missing_preview_specs=missing_preview[:20],  # Limit to 20
+        missing_tags_specs=missing_tags[:20],  # Limit to 20
+        system=system_health,
+        specs=specs_status,
+    )

app/src/components/Header.tsx

@@ -1,7 +1,7 @@
-import { memo, useState, useEffect } from 'react';
+import { memo, useState, useEffect, useRef } from 'react';
+import { useNavigate } from 'react-router-dom';
 import Box from '@mui/material/Box';
 import Typography from '@mui/material/Typography';
-import Link from '@mui/material/Link';
 import Tooltip from '@mui/material/Tooltip';
 import ClickAwayListener from '@mui/material/ClickAwayListener';
 import useMediaQuery from '@mui/material/useMediaQuery';
@@ -15,10 +15,13 @@ interface HeaderProps {
 
 export const Header = memo(function Header({ stats, onRandom }: HeaderProps) {
   const theme = useTheme();
+  const navigate = useNavigate();
   const isXs = useMediaQuery(theme.breakpoints.down('sm'));
   const isSm = useMediaQuery(theme.breakpoints.between('sm', 'md'));
   const [tooltipOpen, setTooltipOpen] = useState(false);
   const [pinned, setPinned] = useState(false);  // true = opened via click, stays open
+  const clickCountRef = useRef(0);
+  const clickTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const tooltipText = stats
     ? `${stats.plots} plots across ${stats.libraries} libraries`
     : '';
@@ -56,16 +59,26 @@ export const Header = memo(function Header({ stats, onRandom }: HeaderProps) {
           fontSize: { xs: '2rem', sm: '2.75rem', md: '3.75rem' },
         }}
       >
-        <Link
-          href="https://pyplots.ai"
-          target="_blank"
-          rel="noopener noreferrer"
-          underline="none"
+        <Box
+          component="span"
+          onClick={(e) => {
+            e.preventDefault();
+            clickCountRef.current += 1;
+            if (clickTimerRef.current) clearTimeout(clickTimerRef.current);
+            clickTimerRef.current = setTimeout(() => {
+              clickCountRef.current = 0;
+            }, 400);
+            if (clickCountRef.current >= 3) {
+              clickCountRef.current = 0;
+              navigate('/debug');
+            }
+          }}
+          sx={{ cursor: 'pointer', userSelect: 'none' }}
         >
           <Box component="span" sx={{ color: '#3776AB' }}>py</Box>
           <Box component="span" sx={{ color: '#FFD43B' }}>plots</Box>
           <Box component="span" sx={{ color: '#1f2937' }}>.ai</Box>
-        </Link>
+        </Box>
         {onRandom && (
           <ShuffleIcon
             tabIndex={0}