feat: add analytics dashboard with pageview tracking and query metrics

.gitignore

@@ -17,3 +17,6 @@ frontend/.openclaude/
 # Build artifacts
 frontend/next-env.d.ts
 CLAUDE 2.md
+
+# Trace logs
+*.log

backend/.env.example

@@ -2,3 +2,4 @@ OPENAI_API_KEY="YOUR_KEY"
 QDRANT_URL=http://qdrant:6333
 QDRANT_CLOUD_API_KEY="YOUR_KEY"
 DATABASE_CONNECTION_STRING=postgresql://npmatch:npmatch@postgres:5432/npmatch
+ANALYTICS_TOKEN="YOUR_TOKEN"

backend/app/analytics.py

@@ -0,0 +1,152 @@
+import hashlib
+import logging
+import os
+from datetime import UTC, datetime, timedelta
+
+from fastapi import Request
+
+from app.db import get_pool
+
+logger = logging.getLogger(__name__)
+
+SEARCH_EVENT_INSERT = """
+INSERT INTO search_events (query, framework, priorities, result_count, ip_hash, user_agent)
+VALUES ($1, $2, $3, $4, $5, $6)
+"""
+
+
+def hash_ip(ip: str) -> str:
+ """SHA-256 hash of the client IP, salted so it isn't reversible."""
+ salt = os.environ.get("ANALYTICS_SALT", "npmatch")
+ return hashlib.sha256(f"{salt}:{ip}".encode()).hexdigest()
+
+
+def client_ip(request: Request) -> str:
+ """Client IP, honoring X-Forwarded-For (set by the Next.js proxy)."""
+ forwarded = request.headers.get("x-forwarded-for")
+ if forwarded:
+ return forwarded.split(",")[0].strip()
+ if request.client:
+ return request.client.host
+ return "unknown"
+
+
+async def record_page_view(*, ip_hash: str, user_agent: str | None, referrer: str | None) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ "INSERT INTO page_views (ip_hash, user_agent, referrer) VALUES ($1, $2, $3)",
+ ip_hash,
+ user_agent,
+ referrer,
+ )
+
+
+async def record_search(
+ *,
+ query: str,
+ framework: str | None,
+ priorities: list[str] | None,
+ result_count: int,
+ ip_hash: str,
+ user_agent: str | None,
+) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ SEARCH_EVENT_INSERT,
+ query,
+ framework,
+ ", ".join(priorities) if priorities else None,
+ result_count,
+ ip_hash,
+ user_agent,
+ )
+
+
+async def get_analytics_summary() -> dict:
+ pool = await get_pool()
+ cutoff = datetime.now(UTC) - timedelta(hours=24)
+
+ row = await pool.fetchrow(
+ """
+ SELECT
+ (SELECT count(*) FROM page_views) AS total_visits,
+ (SELECT count(DISTINCT ip_hash) FROM page_views) AS unique_visitors,
+ (SELECT count(*) FROM search_events) AS total_searches,
+ (SELECT count(*) FROM page_views WHERE visited_at >= $1) AS visits_last_24h,
+ (SELECT count(*) FROM search_events WHERE searched_at >= $1) AS searches_last_24h
+ """,
+ cutoff,
+ )
+
+ top_queries = await pool.fetch(
+ """
+ SELECT query, count(*) AS count
+ FROM search_events
+ GROUP BY query
+ ORDER BY count DESC, query ASC
+ LIMIT 10
+ """
+ )
+ top_frameworks = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(framework, ''), 'any') AS framework, count(*) AS count
+ FROM search_events
+ GROUP BY COALESCE(NULLIF(framework, ''), 'any')
+ ORDER BY count DESC, framework ASC
+ LIMIT 10
+ """
+ )
+ top_referrers = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(referrer, ''), '(direct)') AS referrer, count(*) AS count
+ FROM page_views
+ GROUP BY COALESCE(NULLIF(referrer, ''), '(direct)')
+ ORDER BY count DESC, referrer ASC
+ LIMIT 10
+ """
+ )
+
+ return {
+ "total_visits": row["total_visits"],
+ "unique_visitors": row["unique_visitors"],
+ "total_searches": row["total_searches"],
+ "visits_last_24h": row["visits_last_24h"],
+ "searches_last_24h": row["searches_last_24h"],
+ "top_queries": [{"label": r["query"], "count": r["count"]} for r in top_queries],
+ "top_frameworks": [{"label": r["framework"], "count": r["count"]} for r in top_frameworks],
+ "top_referrers": [{"label": r["referrer"], "count": r["count"]} for r in top_referrers],
+ }
+
+
+async def list_page_views(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT visited_at, ip_hash, user_agent, referrer
+ FROM page_views
+ ORDER BY visited_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ return [dict(r) for r in rows]
+
+
+async def list_searches(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT searched_at, query, framework, priorities, result_count
+ FROM search_events
+ ORDER BY searched_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ out = []
+ for row in rows:
+ item = dict(row)
+ priorities = item["priorities"]
+ item["priorities"] = [p.strip() for p in priorities.split(",")] if priorities else None
+ out.append(item)
+ return out

backend/app/db.py

@@ -0,0 +1,19 @@
+import os
+
+import asyncpg
+
+_pg_pool: asyncpg.Pool | None = None
+
+
+async def get_pool() -> asyncpg.Pool:
+ """Lazy initialization of the shared asyncpg pool."""
+ global _pg_pool
+
+ if _pg_pool is None:
+ _pg_pool = await asyncpg.create_pool(
+ dsn=os.environ["DATABASE_CONNECTION_STRING"],
+ min_size=1,
+ max_size=5,
+ )
+
+ return _pg_pool

backend/app/main.py

@@ -10,6 +10,15 @@
 from slowapi.util import get_remote_address
 
 import app.env
+from app.analytics import (
+ client_ip,
+ get_analytics_summary,
+ hash_ip,
+ list_page_views,
+ list_searches,
+ record_page_view,
+ record_search,
+)
 from app.llm import stream_response
 from app.models import SearchRequest
 from app.search import package_search
@@ -50,6 +59,66 @@ async def health():
  return {"status": "ok"}
 
 
+def _require_analytics_token(request: Request) -> None:
+ expected = os.environ.get("ANALYTICS_TOKEN")
+ if not expected:
+ raise HTTPException(status_code=503, detail="Analytics token not configured")
+ if request.headers.get("x-analytics-token") != expected:
+ raise HTTPException(status_code=401, detail="Unauthorized")
+
+
+@app.post("/api/track/pageview")
+@limiter.limit("120/minute")
+async def track_pageview(request: Request):
+ referrer = None
+ try:
+ body = await request.json()
+ referrer = body.get("referrer")
+ except Exception:
+ pass
+
+ try:
+ await record_page_view(
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ referrer=referrer or request.headers.get("referer"),
+ )
+ except Exception as e:
+ logger.warning(f"Failed to record page view: {e}")
+
+ return {"ok": True}
+
+
+@app.get("/api/analytics/summary")
+async def analytics_summary(request: Request):
+ _require_analytics_token(request)
+ try:
+ return await get_analytics_summary()
+ except Exception:
+ logger.exception("Analytics summary failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/visits")
+async def analytics_visits(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_page_views(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics visits failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/searches")
+async def analytics_searches(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_searches(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics searches failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
 @app.post("/api/search")
 @limiter.limit("2/minute")
 async def search(request: Request, body: SearchRequest):
@@ -60,9 +129,21 @@ async def search(request: Request, body: SearchRequest):
 
  try:
  packages = await package_search(body.query)
+ except Exception:
+ logger.exception("Package search failed")
+ raise HTTPException(status_code=502, detail="Failed in hybrid search") from None
+
+ try:
+ await record_search(
+ query=body.query,
+ framework=body.framework,
+ priorities=body.priorities,
+ result_count=len(packages),
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ )
  except Exception as e:
- logger.error(f"Package search failed: {e}")
- raise HTTPException(status_code=502, detail="Failed in hybrid search") from e
+ logger.warning(f"Failed to record search event: {e}")
 
  if not packages:
  logger.info("No packages found for query, returning empty response")

backend/app/models.py

@@ -1,3 +1,5 @@
+from datetime import datetime
+
 from pydantic import BaseModel, Field
 
 
@@ -18,3 +20,34 @@ class Package(BaseModel):
 
 class SearchResponse(BaseModel):
  packages: list[Package]
+
+
+class PageView(BaseModel):
+ visited_at: datetime
+ ip_hash: str
+ user_agent: str | None = None
+ referrer: str | None = None
+
+
+class SearchEvent(BaseModel):
+ searched_at: datetime
+ query: str
+ framework: str | None = None
+ priorities: list[str] | None = None
+ result_count: int
+
+
+class TopItem(BaseModel):
+ label: str
+ count: int
+
+
+class AnalyticsSummary(BaseModel):
+ total_visits: int
+ unique_visitors: int
+ total_searches: int
+ visits_last_24h: int
+ searches_last_24h: int
+ top_queries: list[TopItem]
+ top_frameworks: list[TopItem]
+ top_referrers: list[TopItem]

backend/app/search.py

@@ -2,10 +2,11 @@
 import logging
 import os
 
-import asyncpg
 from openai import AsyncOpenAI
 from qdrant_client import AsyncQdrantClient
 
+from app.db import get_pool
+
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
@@ -40,19 +41,6 @@ def get_qdrant_client() -> AsyncQdrantClient:
 COLLECTION_NAME = "npmatch"
 CANDIDATE_LIMIT = 20
 
-_pg_pool: asyncpg.Pool | None = None
-
-
-async def _get_pool() -> asyncpg.Pool:
- global _pg_pool
- if _pg_pool is None:
- _pg_pool = await asyncpg.create_pool(
- dsn=os.environ["DATABASE_CONNECTION_STRING"],
- min_size=1,
- max_size=5,
- )
- return _pg_pool
-
 
 def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
  scores: dict[str, float] = {}
@@ -89,7 +77,7 @@ async def _vector_search(embedding: list[float]) -> list[str]:
 
 
 async def _fts_search(query: str) -> list[str]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  """
  SELECT name,
@@ -115,7 +103,7 @@ def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
 
 
 async def _fetch_metadata(names: list[str]) -> list[dict]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  "SELECT name, description, keywords, version FROM packages WHERE name = ANY($1)",
  names,

.gitignore

@@ -17,3 +17,6 @@ frontend/.openclaude/
 # Build artifacts
 frontend/next-env.d.ts
 CLAUDE 2.md
+
+# Trace logs
+*.log

backend/.env.example

@@ -2,3 +2,4 @@ OPENAI_API_KEY="YOUR_KEY"
 QDRANT_URL=http://qdrant:6333
 QDRANT_CLOUD_API_KEY="YOUR_KEY"
 DATABASE_CONNECTION_STRING=postgresql://npmatch:npmatch@postgres:5432/npmatch
+ANALYTICS_TOKEN="YOUR_TOKEN"

backend/app/analytics.py

@@ -0,0 +1,152 @@
+import hashlib
+import logging
+import os
+from datetime import UTC, datetime, timedelta
+
+from fastapi import Request
+
+from app.db import get_pool
+
+logger = logging.getLogger(__name__)
+
+SEARCH_EVENT_INSERT = """
+INSERT INTO search_events (query, framework, priorities, result_count, ip_hash, user_agent)
+VALUES ($1, $2, $3, $4, $5, $6)
+"""
+
+
+def hash_ip(ip: str) -> str:
+ """SHA-256 hash of the client IP, salted so it isn't reversible."""
+ salt = os.environ.get("ANALYTICS_SALT", "npmatch")
+ return hashlib.sha256(f"{salt}:{ip}".encode()).hexdigest()
+
+
+def client_ip(request: Request) -> str:
+ """Client IP, honoring X-Forwarded-For (set by the Next.js proxy)."""
+ forwarded = request.headers.get("x-forwarded-for")
+ if forwarded:
+ return forwarded.split(",")[0].strip()
+ if request.client:
+ return request.client.host
+ return "unknown"
+
+
+async def record_page_view(*, ip_hash: str, user_agent: str | None, referrer: str | None) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ "INSERT INTO page_views (ip_hash, user_agent, referrer) VALUES ($1, $2, $3)",
+ ip_hash,
+ user_agent,
+ referrer,
+ )
+
+
+async def record_search(
+ *,
+ query: str,
+ framework: str | None,
+ priorities: list[str] | None,
+ result_count: int,
+ ip_hash: str,
+ user_agent: str | None,
+) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ SEARCH_EVENT_INSERT,
+ query,
+ framework,
+ ", ".join(priorities) if priorities else None,
+ result_count,
+ ip_hash,
+ user_agent,
+ )
+
+
+async def get_analytics_summary() -> dict:
+ pool = await get_pool()
+ cutoff = datetime.now(UTC) - timedelta(hours=24)
+
+ row = await pool.fetchrow(
+ """
+ SELECT
+ (SELECT count(*) FROM page_views) AS total_visits,
+ (SELECT count(DISTINCT ip_hash) FROM page_views) AS unique_visitors,
+ (SELECT count(*) FROM search_events) AS total_searches,
+ (SELECT count(*) FROM page_views WHERE visited_at >= $1) AS visits_last_24h,
+ (SELECT count(*) FROM search_events WHERE searched_at >= $1) AS searches_last_24h
+ """,
+ cutoff,
+ )
+
+ top_queries = await pool.fetch(
+ """
+ SELECT query, count(*) AS count
+ FROM search_events
+ GROUP BY query
+ ORDER BY count DESC, query ASC
+ LIMIT 10
+ """
+ )
+ top_frameworks = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(framework, ''), 'any') AS framework, count(*) AS count
+ FROM search_events
+ GROUP BY COALESCE(NULLIF(framework, ''), 'any')
+ ORDER BY count DESC, framework ASC
+ LIMIT 10
+ """
+ )
+ top_referrers = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(referrer, ''), '(direct)') AS referrer, count(*) AS count
+ FROM page_views
+ GROUP BY COALESCE(NULLIF(referrer, ''), '(direct)')
+ ORDER BY count DESC, referrer ASC
+ LIMIT 10
+ """
+ )
+
+ return {
+ "total_visits": row["total_visits"],
+ "unique_visitors": row["unique_visitors"],
+ "total_searches": row["total_searches"],
+ "visits_last_24h": row["visits_last_24h"],
+ "searches_last_24h": row["searches_last_24h"],
+ "top_queries": [{"label": r["query"], "count": r["count"]} for r in top_queries],
+ "top_frameworks": [{"label": r["framework"], "count": r["count"]} for r in top_frameworks],
+ "top_referrers": [{"label": r["referrer"], "count": r["count"]} for r in top_referrers],
+ }
+
+
+async def list_page_views(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT visited_at, ip_hash, user_agent, referrer
+ FROM page_views
+ ORDER BY visited_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ return [dict(r) for r in rows]
+
+
+async def list_searches(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT searched_at, query, framework, priorities, result_count
+ FROM search_events
+ ORDER BY searched_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ out = []
+ for row in rows:
+ item = dict(row)
+ priorities = item["priorities"]
+ item["priorities"] = [p.strip() for p in priorities.split(",")] if priorities else None
+ out.append(item)
+ return out

backend/app/db.py

@@ -0,0 +1,19 @@
+import os
+
+import asyncpg
+
+_pg_pool: asyncpg.Pool | None = None
+
+
+async def get_pool() -> asyncpg.Pool:
+ """Lazy initialization of the shared asyncpg pool."""
+ global _pg_pool
+
+ if _pg_pool is None:
+ _pg_pool = await asyncpg.create_pool(
+ dsn=os.environ["DATABASE_CONNECTION_STRING"],
+ min_size=1,
+ max_size=5,
+ )
+
+ return _pg_pool

backend/app/main.py

@@ -10,6 +10,15 @@
 from slowapi.util import get_remote_address
 
 import app.env
+from app.analytics import (
+ client_ip,
+ get_analytics_summary,
+ hash_ip,
+ list_page_views,
+ list_searches,
+ record_page_view,
+ record_search,
+)
 from app.llm import stream_response
 from app.models import SearchRequest
 from app.search import package_search
@@ -50,6 +59,66 @@ async def health():
  return {"status": "ok"}
 
 
+def _require_analytics_token(request: Request) -> None:
+ expected = os.environ.get("ANALYTICS_TOKEN")
+ if not expected:
+ raise HTTPException(status_code=503, detail="Analytics token not configured")
+ if request.headers.get("x-analytics-token") != expected:
+ raise HTTPException(status_code=401, detail="Unauthorized")
+
+
+@app.post("/api/track/pageview")
+@limiter.limit("120/minute")
+async def track_pageview(request: Request):
+ referrer = None
+ try:
+ body = await request.json()
+ referrer = body.get("referrer")
+ except Exception:
+ pass
+
+ try:
+ await record_page_view(
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ referrer=referrer or request.headers.get("referer"),
+ )
+ except Exception as e:
+ logger.warning(f"Failed to record page view: {e}")
+
+ return {"ok": True}
+
+
+@app.get("/api/analytics/summary")
+async def analytics_summary(request: Request):
+ _require_analytics_token(request)
+ try:
+ return await get_analytics_summary()
+ except Exception:
+ logger.exception("Analytics summary failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/visits")
+async def analytics_visits(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_page_views(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics visits failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/searches")
+async def analytics_searches(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_searches(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics searches failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
 @app.post("/api/search")
 @limiter.limit("2/minute")
 async def search(request: Request, body: SearchRequest):
@@ -60,9 +129,21 @@ async def search(request: Request, body: SearchRequest):
 
  try:
  packages = await package_search(body.query)
+ except Exception:
+ logger.exception("Package search failed")
+ raise HTTPException(status_code=502, detail="Failed in hybrid search") from None
+
+ try:
+ await record_search(
+ query=body.query,
+ framework=body.framework,
+ priorities=body.priorities,
+ result_count=len(packages),
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ )
  except Exception as e:
- logger.error(f"Package search failed: {e}")
- raise HTTPException(status_code=502, detail="Failed in hybrid search") from e
+ logger.warning(f"Failed to record search event: {e}")
 
  if not packages:
  logger.info("No packages found for query, returning empty response")

backend/app/models.py

@@ -1,3 +1,5 @@
+from datetime import datetime
+
 from pydantic import BaseModel, Field
 
 
@@ -18,3 +20,34 @@ class Package(BaseModel):
 
 class SearchResponse(BaseModel):
  packages: list[Package]
+
+
+class PageView(BaseModel):
+ visited_at: datetime
+ ip_hash: str
+ user_agent: str | None = None
+ referrer: str | None = None
+
+
+class SearchEvent(BaseModel):
+ searched_at: datetime
+ query: str
+ framework: str | None = None
+ priorities: list[str] | None = None
+ result_count: int
+
+
+class TopItem(BaseModel):
+ label: str
+ count: int
+
+
+class AnalyticsSummary(BaseModel):
+ total_visits: int
+ unique_visitors: int
+ total_searches: int
+ visits_last_24h: int
+ searches_last_24h: int
+ top_queries: list[TopItem]
+ top_frameworks: list[TopItem]
+ top_referrers: list[TopItem]

backend/app/search.py

@@ -2,10 +2,11 @@
 import logging
 import os
 
-import asyncpg
 from openai import AsyncOpenAI
 from qdrant_client import AsyncQdrantClient
 
+from app.db import get_pool
+
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
@@ -40,19 +41,6 @@ def get_qdrant_client() -> AsyncQdrantClient:
 COLLECTION_NAME = "npmatch"
 CANDIDATE_LIMIT = 20
 
-_pg_pool: asyncpg.Pool | None = None
-
-
-async def _get_pool() -> asyncpg.Pool:
- global _pg_pool
- if _pg_pool is None:
- _pg_pool = await asyncpg.create_pool(
- dsn=os.environ["DATABASE_CONNECTION_STRING"],
- min_size=1,
- max_size=5,
- )
- return _pg_pool
-
 
 def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
  scores: dict[str, float] = {}
@@ -89,7 +77,7 @@ async def _vector_search(embedding: list[float]) -> list[str]:
 
 
 async def _fts_search(query: str) -> list[str]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  """
  SELECT name,
@@ -115,7 +103,7 @@ def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
 
 
 async def _fetch_metadata(names: list[str]) -> list[dict]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  "SELECT name, description, keywords, version FROM packages WHERE name = ANY($1)",
  names,

.gitignore

@@ -17,3 +17,6 @@ frontend/.openclaude/
 # Build artifacts
 frontend/next-env.d.ts
 CLAUDE 2.md
+
+# Trace logs
+*.log

backend/.env.example

@@ -2,3 +2,4 @@ OPENAI_API_KEY="YOUR_KEY"
 QDRANT_URL=http://qdrant:6333
 QDRANT_CLOUD_API_KEY="YOUR_KEY"
 DATABASE_CONNECTION_STRING=postgresql://npmatch:npmatch@postgres:5432/npmatch
+ANALYTICS_TOKEN="YOUR_TOKEN"

backend/app/analytics.py

@@ -0,0 +1,152 @@
+import hashlib
+import logging
+import os
+from datetime import UTC, datetime, timedelta
+
+from fastapi import Request
+
+from app.db import get_pool
+
+logger = logging.getLogger(__name__)
+
+SEARCH_EVENT_INSERT = """
+INSERT INTO search_events (query, framework, priorities, result_count, ip_hash, user_agent)
+VALUES ($1, $2, $3, $4, $5, $6)
+"""
+
+
+def hash_ip(ip: str) -> str:
+ """SHA-256 hash of the client IP, salted so it isn't reversible."""
+ salt = os.environ.get("ANALYTICS_SALT", "npmatch")
+ return hashlib.sha256(f"{salt}:{ip}".encode()).hexdigest()
+
+
+def client_ip(request: Request) -> str:
+ """Client IP, honoring X-Forwarded-For (set by the Next.js proxy)."""
+ forwarded = request.headers.get("x-forwarded-for")
+ if forwarded:
+ return forwarded.split(",")[0].strip()
+ if request.client:
+ return request.client.host
+ return "unknown"
+
+
+async def record_page_view(*, ip_hash: str, user_agent: str | None, referrer: str | None) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ "INSERT INTO page_views (ip_hash, user_agent, referrer) VALUES ($1, $2, $3)",
+ ip_hash,
+ user_agent,
+ referrer,
+ )
+
+
+async def record_search(
+ *,
+ query: str,
+ framework: str | None,
+ priorities: list[str] | None,
+ result_count: int,
+ ip_hash: str,
+ user_agent: str | None,
+) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ SEARCH_EVENT_INSERT,
+ query,
+ framework,
+ ", ".join(priorities) if priorities else None,
+ result_count,
+ ip_hash,
+ user_agent,
+ )
+
+
+async def get_analytics_summary() -> dict:
+ pool = await get_pool()
+ cutoff = datetime.now(UTC) - timedelta(hours=24)
+
+ row = await pool.fetchrow(
+ """
+ SELECT
+ (SELECT count(*) FROM page_views) AS total_visits,
+ (SELECT count(DISTINCT ip_hash) FROM page_views) AS unique_visitors,
+ (SELECT count(*) FROM search_events) AS total_searches,
+ (SELECT count(*) FROM page_views WHERE visited_at >= $1) AS visits_last_24h,
+ (SELECT count(*) FROM search_events WHERE searched_at >= $1) AS searches_last_24h
+ """,
+ cutoff,
+ )
+
+ top_queries = await pool.fetch(
+ """
+ SELECT query, count(*) AS count
+ FROM search_events
+ GROUP BY query
+ ORDER BY count DESC, query ASC
+ LIMIT 10
+ """
+ )
+ top_frameworks = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(framework, ''), 'any') AS framework, count(*) AS count
+ FROM search_events
+ GROUP BY COALESCE(NULLIF(framework, ''), 'any')
+ ORDER BY count DESC, framework ASC
+ LIMIT 10
+ """
+ )
+ top_referrers = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(referrer, ''), '(direct)') AS referrer, count(*) AS count
+ FROM page_views
+ GROUP BY COALESCE(NULLIF(referrer, ''), '(direct)')
+ ORDER BY count DESC, referrer ASC
+ LIMIT 10
+ """
+ )
+
+ return {
+ "total_visits": row["total_visits"],
+ "unique_visitors": row["unique_visitors"],
+ "total_searches": row["total_searches"],
+ "visits_last_24h": row["visits_last_24h"],
+ "searches_last_24h": row["searches_last_24h"],
+ "top_queries": [{"label": r["query"], "count": r["count"]} for r in top_queries],
+ "top_frameworks": [{"label": r["framework"], "count": r["count"]} for r in top_frameworks],
+ "top_referrers": [{"label": r["referrer"], "count": r["count"]} for r in top_referrers],
+ }
+
+
+async def list_page_views(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT visited_at, ip_hash, user_agent, referrer
+ FROM page_views
+ ORDER BY visited_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ return [dict(r) for r in rows]
+
+
+async def list_searches(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT searched_at, query, framework, priorities, result_count
+ FROM search_events
+ ORDER BY searched_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ out = []
+ for row in rows:
+ item = dict(row)
+ priorities = item["priorities"]
+ item["priorities"] = [p.strip() for p in priorities.split(",")] if priorities else None
+ out.append(item)
+ return out

backend/app/db.py

@@ -0,0 +1,19 @@
+import os
+
+import asyncpg
+
+_pg_pool: asyncpg.Pool | None = None
+
+
+async def get_pool() -> asyncpg.Pool:
+ """Lazy initialization of the shared asyncpg pool."""
+ global _pg_pool
+
+ if _pg_pool is None:
+ _pg_pool = await asyncpg.create_pool(
+ dsn=os.environ["DATABASE_CONNECTION_STRING"],
+ min_size=1,
+ max_size=5,
+ )
+
+ return _pg_pool

backend/app/main.py

@@ -10,6 +10,15 @@
 from slowapi.util import get_remote_address
 
 import app.env
+from app.analytics import (
+ client_ip,
+ get_analytics_summary,
+ hash_ip,
+ list_page_views,
+ list_searches,
+ record_page_view,
+ record_search,
+)
 from app.llm import stream_response
 from app.models import SearchRequest
 from app.search import package_search
@@ -50,6 +59,66 @@ async def health():
  return {"status": "ok"}
 
 
+def _require_analytics_token(request: Request) -> None:
+ expected = os.environ.get("ANALYTICS_TOKEN")
+ if not expected:
+ raise HTTPException(status_code=503, detail="Analytics token not configured")
+ if request.headers.get("x-analytics-token") != expected:
+ raise HTTPException(status_code=401, detail="Unauthorized")
+
+
+@app.post("/api/track/pageview")
+@limiter.limit("120/minute")
+async def track_pageview(request: Request):
+ referrer = None
+ try:
+ body = await request.json()
+ referrer = body.get("referrer")
+ except Exception:
+ pass
+
+ try:
+ await record_page_view(
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ referrer=referrer or request.headers.get("referer"),
+ )
+ except Exception as e:
+ logger.warning(f"Failed to record page view: {e}")
+
+ return {"ok": True}
+
+
+@app.get("/api/analytics/summary")
+async def analytics_summary(request: Request):
+ _require_analytics_token(request)
+ try:
+ return await get_analytics_summary()
+ except Exception:
+ logger.exception("Analytics summary failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/visits")
+async def analytics_visits(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_page_views(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics visits failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/searches")
+async def analytics_searches(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_searches(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics searches failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
 @app.post("/api/search")
 @limiter.limit("2/minute")
 async def search(request: Request, body: SearchRequest):
@@ -60,9 +129,21 @@ async def search(request: Request, body: SearchRequest):
 
  try:
  packages = await package_search(body.query)
+ except Exception:
+ logger.exception("Package search failed")
+ raise HTTPException(status_code=502, detail="Failed in hybrid search") from None
+
+ try:
+ await record_search(
+ query=body.query,
+ framework=body.framework,
+ priorities=body.priorities,
+ result_count=len(packages),
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ )
  except Exception as e:
- logger.error(f"Package search failed: {e}")
- raise HTTPException(status_code=502, detail="Failed in hybrid search") from e
+ logger.warning(f"Failed to record search event: {e}")
 
  if not packages:
  logger.info("No packages found for query, returning empty response")

backend/app/models.py

@@ -1,3 +1,5 @@
+from datetime import datetime
+
 from pydantic import BaseModel, Field
 
 
@@ -18,3 +20,34 @@ class Package(BaseModel):
 
 class SearchResponse(BaseModel):
  packages: list[Package]
+
+
+class PageView(BaseModel):
+ visited_at: datetime
+ ip_hash: str
+ user_agent: str | None = None
+ referrer: str | None = None
+
+
+class SearchEvent(BaseModel):
+ searched_at: datetime
+ query: str
+ framework: str | None = None
+ priorities: list[str] | None = None
+ result_count: int
+
+
+class TopItem(BaseModel):
+ label: str
+ count: int
+
+
+class AnalyticsSummary(BaseModel):
+ total_visits: int
+ unique_visitors: int
+ total_searches: int
+ visits_last_24h: int
+ searches_last_24h: int
+ top_queries: list[TopItem]
+ top_frameworks: list[TopItem]
+ top_referrers: list[TopItem]

backend/app/search.py

@@ -2,10 +2,11 @@
 import logging
 import os
 
-import asyncpg
 from openai import AsyncOpenAI
 from qdrant_client import AsyncQdrantClient
 
+from app.db import get_pool
+
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
@@ -40,19 +41,6 @@ def get_qdrant_client() -> AsyncQdrantClient:
 COLLECTION_NAME = "npmatch"
 CANDIDATE_LIMIT = 20
 
-_pg_pool: asyncpg.Pool | None = None
-
-
-async def _get_pool() -> asyncpg.Pool:
- global _pg_pool
- if _pg_pool is None:
- _pg_pool = await asyncpg.create_pool(
- dsn=os.environ["DATABASE_CONNECTION_STRING"],
- min_size=1,
- max_size=5,
- )
- return _pg_pool
-
 
 def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
  scores: dict[str, float] = {}
@@ -89,7 +77,7 @@ async def _vector_search(embedding: list[float]) -> list[str]:
 
 
 async def _fts_search(query: str) -> list[str]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  """
  SELECT name,
@@ -115,7 +103,7 @@ def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
 
 
 async def _fetch_metadata(names: list[str]) -> list[dict]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  "SELECT name, description, keywords, version FROM packages WHERE name = ANY($1)",
  names,

.gitignore

@@ -17,3 +17,6 @@ frontend/.openclaude/
 # Build artifacts
 frontend/next-env.d.ts
 CLAUDE 2.md
+
+# Trace logs
+*.log

backend/.env.example

@@ -2,3 +2,4 @@ OPENAI_API_KEY="YOUR_KEY"
 QDRANT_URL=http://qdrant:6333
 QDRANT_CLOUD_API_KEY="YOUR_KEY"
 DATABASE_CONNECTION_STRING=postgresql://npmatch:npmatch@postgres:5432/npmatch
+ANALYTICS_TOKEN="YOUR_TOKEN"

backend/app/analytics.py

@@ -0,0 +1,152 @@
+import hashlib
+import logging
+import os
+from datetime import UTC, datetime, timedelta
+
+from fastapi import Request
+
+from app.db import get_pool
+
+logger = logging.getLogger(__name__)
+
+SEARCH_EVENT_INSERT = """
+INSERT INTO search_events (query, framework, priorities, result_count, ip_hash, user_agent)
+VALUES ($1, $2, $3, $4, $5, $6)
+"""
+
+
+def hash_ip(ip: str) -> str:
+ """SHA-256 hash of the client IP, salted so it isn't reversible."""
+ salt = os.environ.get("ANALYTICS_SALT", "npmatch")
+ return hashlib.sha256(f"{salt}:{ip}".encode()).hexdigest()
+
+
+def client_ip(request: Request) -> str:
+ """Client IP, honoring X-Forwarded-For (set by the Next.js proxy)."""
+ forwarded = request.headers.get("x-forwarded-for")
+ if forwarded:
+ return forwarded.split(",")[0].strip()
+ if request.client:
+ return request.client.host
+ return "unknown"
+
+
+async def record_page_view(*, ip_hash: str, user_agent: str | None, referrer: str | None) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ "INSERT INTO page_views (ip_hash, user_agent, referrer) VALUES ($1, $2, $3)",
+ ip_hash,
+ user_agent,
+ referrer,
+ )
+
+
+async def record_search(
+ *,
+ query: str,
+ framework: str | None,
+ priorities: list[str] | None,
+ result_count: int,
+ ip_hash: str,
+ user_agent: str | None,
+) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ SEARCH_EVENT_INSERT,
+ query,
+ framework,
+ ", ".join(priorities) if priorities else None,
+ result_count,
+ ip_hash,
+ user_agent,
+ )
+
+
+async def get_analytics_summary() -> dict:
+ pool = await get_pool()
+ cutoff = datetime.now(UTC) - timedelta(hours=24)
+
+ row = await pool.fetchrow(
+ """
+ SELECT
+ (SELECT count(*) FROM page_views) AS total_visits,
+ (SELECT count(DISTINCT ip_hash) FROM page_views) AS unique_visitors,
+ (SELECT count(*) FROM search_events) AS total_searches,
+ (SELECT count(*) FROM page_views WHERE visited_at >= $1) AS visits_last_24h,
+ (SELECT count(*) FROM search_events WHERE searched_at >= $1) AS searches_last_24h
+ """,
+ cutoff,
+ )
+
+ top_queries = await pool.fetch(
+ """
+ SELECT query, count(*) AS count
+ FROM search_events
+ GROUP BY query
+ ORDER BY count DESC, query ASC
+ LIMIT 10
+ """
+ )
+ top_frameworks = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(framework, ''), 'any') AS framework, count(*) AS count
+ FROM search_events
+ GROUP BY COALESCE(NULLIF(framework, ''), 'any')
+ ORDER BY count DESC, framework ASC
+ LIMIT 10
+ """
+ )
+ top_referrers = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(referrer, ''), '(direct)') AS referrer, count(*) AS count
+ FROM page_views
+ GROUP BY COALESCE(NULLIF(referrer, ''), '(direct)')
+ ORDER BY count DESC, referrer ASC
+ LIMIT 10
+ """
+ )
+
+ return {
+ "total_visits": row["total_visits"],
+ "unique_visitors": row["unique_visitors"],
+ "total_searches": row["total_searches"],
+ "visits_last_24h": row["visits_last_24h"],
+ "searches_last_24h": row["searches_last_24h"],
+ "top_queries": [{"label": r["query"], "count": r["count"]} for r in top_queries],
+ "top_frameworks": [{"label": r["framework"], "count": r["count"]} for r in top_frameworks],
+ "top_referrers": [{"label": r["referrer"], "count": r["count"]} for r in top_referrers],
+ }
+
+
+async def list_page_views(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT visited_at, ip_hash, user_agent, referrer
+ FROM page_views
+ ORDER BY visited_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ return [dict(r) for r in rows]
+
+
+async def list_searches(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT searched_at, query, framework, priorities, result_count
+ FROM search_events
+ ORDER BY searched_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ out = []
+ for row in rows:
+ item = dict(row)
+ priorities = item["priorities"]
+ item["priorities"] = [p.strip() for p in priorities.split(",")] if priorities else None
+ out.append(item)
+ return out

backend/app/db.py

@@ -0,0 +1,19 @@
+import os
+
+import asyncpg
+
+_pg_pool: asyncpg.Pool | None = None
+
+
+async def get_pool() -> asyncpg.Pool:
+ """Lazy initialization of the shared asyncpg pool."""
+ global _pg_pool
+
+ if _pg_pool is None:
+ _pg_pool = await asyncpg.create_pool(
+ dsn=os.environ["DATABASE_CONNECTION_STRING"],
+ min_size=1,
+ max_size=5,
+ )
+
+ return _pg_pool

backend/app/main.py

@@ -10,6 +10,15 @@
 from slowapi.util import get_remote_address
 
 import app.env
+from app.analytics import (
+ client_ip,
+ get_analytics_summary,
+ hash_ip,
+ list_page_views,
+ list_searches,
+ record_page_view,
+ record_search,
+)
 from app.llm import stream_response
 from app.models import SearchRequest
 from app.search import package_search
@@ -50,6 +59,66 @@ async def health():
  return {"status": "ok"}
 
 
+def _require_analytics_token(request: Request) -> None:
+ expected = os.environ.get("ANALYTICS_TOKEN")
+ if not expected:
+ raise HTTPException(status_code=503, detail="Analytics token not configured")
+ if request.headers.get("x-analytics-token") != expected:
+ raise HTTPException(status_code=401, detail="Unauthorized")
+
+
+@app.post("/api/track/pageview")
+@limiter.limit("120/minute")
+async def track_pageview(request: Request):
+ referrer = None
+ try:
+ body = await request.json()
+ referrer = body.get("referrer")
+ except Exception:
+ pass
+
+ try:
+ await record_page_view(
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ referrer=referrer or request.headers.get("referer"),
+ )
+ except Exception as e:
+ logger.warning(f"Failed to record page view: {e}")
+
+ return {"ok": True}
+
+
+@app.get("/api/analytics/summary")
+async def analytics_summary(request: Request):
+ _require_analytics_token(request)
+ try:
+ return await get_analytics_summary()
+ except Exception:
+ logger.exception("Analytics summary failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/visits")
+async def analytics_visits(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_page_views(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics visits failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/searches")
+async def analytics_searches(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_searches(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics searches failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
 @app.post("/api/search")
 @limiter.limit("2/minute")
 async def search(request: Request, body: SearchRequest):
@@ -60,9 +129,21 @@ async def search(request: Request, body: SearchRequest):
 
  try:
  packages = await package_search(body.query)
+ except Exception:
+ logger.exception("Package search failed")
+ raise HTTPException(status_code=502, detail="Failed in hybrid search") from None
+
+ try:
+ await record_search(
+ query=body.query,
+ framework=body.framework,
+ priorities=body.priorities,
+ result_count=len(packages),
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ )
  except Exception as e:
- logger.error(f"Package search failed: {e}")
- raise HTTPException(status_code=502, detail="Failed in hybrid search") from e
+ logger.warning(f"Failed to record search event: {e}")
 
  if not packages:
  logger.info("No packages found for query, returning empty response")

backend/app/models.py

@@ -1,3 +1,5 @@
+from datetime import datetime
+
 from pydantic import BaseModel, Field
 
 
@@ -18,3 +20,34 @@ class Package(BaseModel):
 
 class SearchResponse(BaseModel):
  packages: list[Package]
+
+
+class PageView(BaseModel):
+ visited_at: datetime
+ ip_hash: str
+ user_agent: str | None = None
+ referrer: str | None = None
+
+
+class SearchEvent(BaseModel):
+ searched_at: datetime
+ query: str
+ framework: str | None = None
+ priorities: list[str] | None = None
+ result_count: int
+
+
+class TopItem(BaseModel):
+ label: str
+ count: int
+
+
+class AnalyticsSummary(BaseModel):
+ total_visits: int
+ unique_visitors: int
+ total_searches: int
+ visits_last_24h: int
+ searches_last_24h: int
+ top_queries: list[TopItem]
+ top_frameworks: list[TopItem]
+ top_referrers: list[TopItem]

backend/app/search.py

@@ -2,10 +2,11 @@
 import logging
 import os
 
-import asyncpg
 from openai import AsyncOpenAI
 from qdrant_client import AsyncQdrantClient
 
+from app.db import get_pool
+
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
@@ -40,19 +41,6 @@ def get_qdrant_client() -> AsyncQdrantClient:
 COLLECTION_NAME = "npmatch"
 CANDIDATE_LIMIT = 20
 
-_pg_pool: asyncpg.Pool | None = None
-
-
-async def _get_pool() -> asyncpg.Pool:
- global _pg_pool
- if _pg_pool is None:
- _pg_pool = await asyncpg.create_pool(
- dsn=os.environ["DATABASE_CONNECTION_STRING"],
- min_size=1,
- max_size=5,
- )
- return _pg_pool
-
 
 def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
  scores: dict[str, float] = {}
@@ -89,7 +77,7 @@ async def _vector_search(embedding: list[float]) -> list[str]:
 
 
 async def _fts_search(query: str) -> list[str]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  """
  SELECT name,
@@ -115,7 +103,7 @@ def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
 
 
 async def _fetch_metadata(names: list[str]) -> list[dict]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  "SELECT name, description, keywords, version FROM packages WHERE name = ANY($1)",
  names,

.gitignore

@@ -17,3 +17,6 @@ frontend/.openclaude/
 # Build artifacts
 frontend/next-env.d.ts
 CLAUDE 2.md
+
+# Trace logs
+*.log

backend/.env.example

@@ -2,3 +2,4 @@ OPENAI_API_KEY="YOUR_KEY"
 QDRANT_URL=http://qdrant:6333
 QDRANT_CLOUD_API_KEY="YOUR_KEY"
 DATABASE_CONNECTION_STRING=postgresql://npmatch:npmatch@postgres:5432/npmatch
+ANALYTICS_TOKEN="YOUR_TOKEN"

backend/app/analytics.py

@@ -0,0 +1,152 @@
+import hashlib
+import logging
+import os
+from datetime import UTC, datetime, timedelta
+
+from fastapi import Request
+
+from app.db import get_pool
+
+logger = logging.getLogger(__name__)
+
+SEARCH_EVENT_INSERT = """
+INSERT INTO search_events (query, framework, priorities, result_count, ip_hash, user_agent)
+VALUES ($1, $2, $3, $4, $5, $6)
+"""
+
+
+def hash_ip(ip: str) -> str:
+ """SHA-256 hash of the client IP, salted so it isn't reversible."""
+ salt = os.environ.get("ANALYTICS_SALT", "npmatch")
+ return hashlib.sha256(f"{salt}:{ip}".encode()).hexdigest()
+
+
+def client_ip(request: Request) -> str:
+ """Client IP, honoring X-Forwarded-For (set by the Next.js proxy)."""
+ forwarded = request.headers.get("x-forwarded-for")
+ if forwarded:
+ return forwarded.split(",")[0].strip()
+ if request.client:
+ return request.client.host
+ return "unknown"
+
+
+async def record_page_view(*, ip_hash: str, user_agent: str | None, referrer: str | None) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ "INSERT INTO page_views (ip_hash, user_agent, referrer) VALUES ($1, $2, $3)",
+ ip_hash,
+ user_agent,
+ referrer,
+ )
+
+
+async def record_search(
+ *,
+ query: str,
+ framework: str | None,
+ priorities: list[str] | None,
+ result_count: int,
+ ip_hash: str,
+ user_agent: str | None,
+) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ SEARCH_EVENT_INSERT,
+ query,
+ framework,
+ ", ".join(priorities) if priorities else None,
+ result_count,
+ ip_hash,
+ user_agent,
+ )
+
+
+async def get_analytics_summary() -> dict:
+ pool = await get_pool()
+ cutoff = datetime.now(UTC) - timedelta(hours=24)
+
+ row = await pool.fetchrow(
+ """
+ SELECT
+ (SELECT count(*) FROM page_views) AS total_visits,
+ (SELECT count(DISTINCT ip_hash) FROM page_views) AS unique_visitors,
+ (SELECT count(*) FROM search_events) AS total_searches,
+ (SELECT count(*) FROM page_views WHERE visited_at >= $1) AS visits_last_24h,
+ (SELECT count(*) FROM search_events WHERE searched_at >= $1) AS searches_last_24h
+ """,
+ cutoff,
+ )
+
+ top_queries = await pool.fetch(
+ """
+ SELECT query, count(*) AS count
+ FROM search_events
+ GROUP BY query
+ ORDER BY count DESC, query ASC
+ LIMIT 10
+ """
+ )
+ top_frameworks = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(framework, ''), 'any') AS framework, count(*) AS count
+ FROM search_events
+ GROUP BY COALESCE(NULLIF(framework, ''), 'any')
+ ORDER BY count DESC, framework ASC
+ LIMIT 10
+ """
+ )
+ top_referrers = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(referrer, ''), '(direct)') AS referrer, count(*) AS count
+ FROM page_views
+ GROUP BY COALESCE(NULLIF(referrer, ''), '(direct)')
+ ORDER BY count DESC, referrer ASC
+ LIMIT 10
+ """
+ )
+
+ return {
+ "total_visits": row["total_visits"],
+ "unique_visitors": row["unique_visitors"],
+ "total_searches": row["total_searches"],
+ "visits_last_24h": row["visits_last_24h"],
+ "searches_last_24h": row["searches_last_24h"],
+ "top_queries": [{"label": r["query"], "count": r["count"]} for r in top_queries],
+ "top_frameworks": [{"label": r["framework"], "count": r["count"]} for r in top_frameworks],
+ "top_referrers": [{"label": r["referrer"], "count": r["count"]} for r in top_referrers],
+ }
+
+
+async def list_page_views(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT visited_at, ip_hash, user_agent, referrer
+ FROM page_views
+ ORDER BY visited_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ return [dict(r) for r in rows]
+
+
+async def list_searches(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT searched_at, query, framework, priorities, result_count
+ FROM search_events
+ ORDER BY searched_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ out = []
+ for row in rows:
+ item = dict(row)
+ priorities = item["priorities"]
+ item["priorities"] = [p.strip() for p in priorities.split(",")] if priorities else None
+ out.append(item)
+ return out

backend/app/db.py

@@ -0,0 +1,19 @@
+import os
+
+import asyncpg
+
+_pg_pool: asyncpg.Pool | None = None
+
+
+async def get_pool() -> asyncpg.Pool:
+ """Lazy initialization of the shared asyncpg pool."""
+ global _pg_pool
+
+ if _pg_pool is None:
+ _pg_pool = await asyncpg.create_pool(
+ dsn=os.environ["DATABASE_CONNECTION_STRING"],
+ min_size=1,
+ max_size=5,
+ )
+
+ return _pg_pool

backend/app/main.py

@@ -10,6 +10,15 @@
 from slowapi.util import get_remote_address
 
 import app.env
+from app.analytics import (
+ client_ip,
+ get_analytics_summary,
+ hash_ip,
+ list_page_views,
+ list_searches,
+ record_page_view,
+ record_search,
+)
 from app.llm import stream_response
 from app.models import SearchRequest
 from app.search import package_search
@@ -50,6 +59,66 @@ async def health():
  return {"status": "ok"}
 
 
+def _require_analytics_token(request: Request) -> None:
+ expected = os.environ.get("ANALYTICS_TOKEN")
+ if not expected:
+ raise HTTPException(status_code=503, detail="Analytics token not configured")
+ if request.headers.get("x-analytics-token") != expected:
+ raise HTTPException(status_code=401, detail="Unauthorized")
+
+
+@app.post("/api/track/pageview")
+@limiter.limit("120/minute")
+async def track_pageview(request: Request):
+ referrer = None
+ try:
+ body = await request.json()
+ referrer = body.get("referrer")
+ except Exception:
+ pass
+
+ try:
+ await record_page_view(
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ referrer=referrer or request.headers.get("referer"),
+ )
+ except Exception as e:
+ logger.warning(f"Failed to record page view: {e}")
+
+ return {"ok": True}
+
+
+@app.get("/api/analytics/summary")
+async def analytics_summary(request: Request):
+ _require_analytics_token(request)
+ try:
+ return await get_analytics_summary()
+ except Exception:
+ logger.exception("Analytics summary failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/visits")
+async def analytics_visits(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_page_views(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics visits failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/searches")
+async def analytics_searches(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_searches(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics searches failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
 @app.post("/api/search")
 @limiter.limit("2/minute")
 async def search(request: Request, body: SearchRequest):
@@ -60,9 +129,21 @@ async def search(request: Request, body: SearchRequest):
 
  try:
  packages = await package_search(body.query)
+ except Exception:
+ logger.exception("Package search failed")
+ raise HTTPException(status_code=502, detail="Failed in hybrid search") from None
+
+ try:
+ await record_search(
+ query=body.query,
+ framework=body.framework,
+ priorities=body.priorities,
+ result_count=len(packages),
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ )
  except Exception as e:
- logger.error(f"Package search failed: {e}")
- raise HTTPException(status_code=502, detail="Failed in hybrid search") from e
+ logger.warning(f"Failed to record search event: {e}")
 
  if not packages:
  logger.info("No packages found for query, returning empty response")

backend/app/models.py

@@ -1,3 +1,5 @@
+from datetime import datetime
+
 from pydantic import BaseModel, Field
 
 
@@ -18,3 +20,34 @@ class Package(BaseModel):
 
 class SearchResponse(BaseModel):
  packages: list[Package]
+
+
+class PageView(BaseModel):
+ visited_at: datetime
+ ip_hash: str
+ user_agent: str | None = None
+ referrer: str | None = None
+
+
+class SearchEvent(BaseModel):
+ searched_at: datetime
+ query: str
+ framework: str | None = None
+ priorities: list[str] | None = None
+ result_count: int
+
+
+class TopItem(BaseModel):
+ label: str
+ count: int
+
+
+class AnalyticsSummary(BaseModel):
+ total_visits: int
+ unique_visitors: int
+ total_searches: int
+ visits_last_24h: int
+ searches_last_24h: int
+ top_queries: list[TopItem]
+ top_frameworks: list[TopItem]
+ top_referrers: list[TopItem]

backend/app/search.py

@@ -2,10 +2,11 @@
 import logging
 import os
 
-import asyncpg
 from openai import AsyncOpenAI
 from qdrant_client import AsyncQdrantClient
 
+from app.db import get_pool
+
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
@@ -40,19 +41,6 @@ def get_qdrant_client() -> AsyncQdrantClient:
 COLLECTION_NAME = "npmatch"
 CANDIDATE_LIMIT = 20
 
-_pg_pool: asyncpg.Pool | None = None
-
-
-async def _get_pool() -> asyncpg.Pool:
- global _pg_pool
- if _pg_pool is None:
- _pg_pool = await asyncpg.create_pool(
- dsn=os.environ["DATABASE_CONNECTION_STRING"],
- min_size=1,
- max_size=5,
- )
- return _pg_pool
-
 
 def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
  scores: dict[str, float] = {}
@@ -89,7 +77,7 @@ async def _vector_search(embedding: list[float]) -> list[str]:
 
 
 async def _fts_search(query: str) -> list[str]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  """
  SELECT name,
@@ -115,7 +103,7 @@ def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
 
 
 async def _fetch_metadata(names: list[str]) -> list[dict]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  "SELECT name, description, keywords, version FROM packages WHERE name = ANY($1)",
  names,

.gitignore

@@ -17,3 +17,6 @@ frontend/.openclaude/
 # Build artifacts
 frontend/next-env.d.ts
 CLAUDE 2.md
+
+# Trace logs
+*.log

backend/.env.example

@@ -2,3 +2,4 @@ OPENAI_API_KEY="YOUR_KEY"
 QDRANT_URL=http://qdrant:6333
 QDRANT_CLOUD_API_KEY="YOUR_KEY"
 DATABASE_CONNECTION_STRING=postgresql://npmatch:npmatch@postgres:5432/npmatch
+ANALYTICS_TOKEN="YOUR_TOKEN"

backend/app/analytics.py

@@ -0,0 +1,152 @@
+import hashlib
+import logging
+import os
+from datetime import UTC, datetime, timedelta
+
+from fastapi import Request
+
+from app.db import get_pool
+
+logger = logging.getLogger(__name__)
+
+SEARCH_EVENT_INSERT = """
+INSERT INTO search_events (query, framework, priorities, result_count, ip_hash, user_agent)
+VALUES ($1, $2, $3, $4, $5, $6)
+"""
+
+
+def hash_ip(ip: str) -> str:
+ """SHA-256 hash of the client IP, salted so it isn't reversible."""
+ salt = os.environ.get("ANALYTICS_SALT", "npmatch")
+ return hashlib.sha256(f"{salt}:{ip}".encode()).hexdigest()
+
+
+def client_ip(request: Request) -> str:
+ """Client IP, honoring X-Forwarded-For (set by the Next.js proxy)."""
+ forwarded = request.headers.get("x-forwarded-for")
+ if forwarded:
+ return forwarded.split(",")[0].strip()
+ if request.client:
+ return request.client.host
+ return "unknown"
+
+
+async def record_page_view(*, ip_hash: str, user_agent: str | None, referrer: str | None) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ "INSERT INTO page_views (ip_hash, user_agent, referrer) VALUES ($1, $2, $3)",
+ ip_hash,
+ user_agent,
+ referrer,
+ )
+
+
+async def record_search(
+ *,
+ query: str,
+ framework: str | None,
+ priorities: list[str] | None,
+ result_count: int,
+ ip_hash: str,
+ user_agent: str | None,
+) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ SEARCH_EVENT_INSERT,
+ query,
+ framework,
+ ", ".join(priorities) if priorities else None,
+ result_count,
+ ip_hash,
+ user_agent,
+ )
+
+
+async def get_analytics_summary() -> dict:
+ pool = await get_pool()
+ cutoff = datetime.now(UTC) - timedelta(hours=24)
+
+ row = await pool.fetchrow(
+ """
+ SELECT
+ (SELECT count(*) FROM page_views) AS total_visits,
+ (SELECT count(DISTINCT ip_hash) FROM page_views) AS unique_visitors,
+ (SELECT count(*) FROM search_events) AS total_searches,
+ (SELECT count(*) FROM page_views WHERE visited_at >= $1) AS visits_last_24h,
+ (SELECT count(*) FROM search_events WHERE searched_at >= $1) AS searches_last_24h
+ """,
+ cutoff,
+ )
+
+ top_queries = await pool.fetch(
+ """
+ SELECT query, count(*) AS count
+ FROM search_events
+ GROUP BY query
+ ORDER BY count DESC, query ASC
+ LIMIT 10
+ """
+ )
+ top_frameworks = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(framework, ''), 'any') AS framework, count(*) AS count
+ FROM search_events
+ GROUP BY COALESCE(NULLIF(framework, ''), 'any')
+ ORDER BY count DESC, framework ASC
+ LIMIT 10
+ """
+ )
+ top_referrers = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(referrer, ''), '(direct)') AS referrer, count(*) AS count
+ FROM page_views
+ GROUP BY COALESCE(NULLIF(referrer, ''), '(direct)')
+ ORDER BY count DESC, referrer ASC
+ LIMIT 10
+ """
+ )
+
+ return {
+ "total_visits": row["total_visits"],
+ "unique_visitors": row["unique_visitors"],
+ "total_searches": row["total_searches"],
+ "visits_last_24h": row["visits_last_24h"],
+ "searches_last_24h": row["searches_last_24h"],
+ "top_queries": [{"label": r["query"], "count": r["count"]} for r in top_queries],
+ "top_frameworks": [{"label": r["framework"], "count": r["count"]} for r in top_frameworks],
+ "top_referrers": [{"label": r["referrer"], "count": r["count"]} for r in top_referrers],
+ }
+
+
+async def list_page_views(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT visited_at, ip_hash, user_agent, referrer
+ FROM page_views
+ ORDER BY visited_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ return [dict(r) for r in rows]
+
+
+async def list_searches(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT searched_at, query, framework, priorities, result_count
+ FROM search_events
+ ORDER BY searched_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ out = []
+ for row in rows:
+ item = dict(row)
+ priorities = item["priorities"]
+ item["priorities"] = [p.strip() for p in priorities.split(",")] if priorities else None
+ out.append(item)
+ return out

backend/app/db.py

@@ -0,0 +1,19 @@
+import os
+
+import asyncpg
+
+_pg_pool: asyncpg.Pool | None = None
+
+
+async def get_pool() -> asyncpg.Pool:
+ """Lazy initialization of the shared asyncpg pool."""
+ global _pg_pool
+
+ if _pg_pool is None:
+ _pg_pool = await asyncpg.create_pool(
+ dsn=os.environ["DATABASE_CONNECTION_STRING"],
+ min_size=1,
+ max_size=5,
+ )
+
+ return _pg_pool

backend/app/main.py

@@ -10,6 +10,15 @@
 from slowapi.util import get_remote_address
 
 import app.env
+from app.analytics import (
+ client_ip,
+ get_analytics_summary,
+ hash_ip,
+ list_page_views,
+ list_searches,
+ record_page_view,
+ record_search,
+)
 from app.llm import stream_response
 from app.models import SearchRequest
 from app.search import package_search
@@ -50,6 +59,66 @@ async def health():
  return {"status": "ok"}
 
 
+def _require_analytics_token(request: Request) -> None:
+ expected = os.environ.get("ANALYTICS_TOKEN")
+ if not expected:
+ raise HTTPException(status_code=503, detail="Analytics token not configured")
+ if request.headers.get("x-analytics-token") != expected:
+ raise HTTPException(status_code=401, detail="Unauthorized")
+
+
+@app.post("/api/track/pageview")
+@limiter.limit("120/minute")
+async def track_pageview(request: Request):
+ referrer = None
+ try:
+ body = await request.json()
+ referrer = body.get("referrer")
+ except Exception:
+ pass
+
+ try:
+ await record_page_view(
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ referrer=referrer or request.headers.get("referer"),
+ )
+ except Exception as e:
+ logger.warning(f"Failed to record page view: {e}")
+
+ return {"ok": True}
+
+
+@app.get("/api/analytics/summary")
+async def analytics_summary(request: Request):
+ _require_analytics_token(request)
+ try:
+ return await get_analytics_summary()
+ except Exception:
+ logger.exception("Analytics summary failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/visits")
+async def analytics_visits(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_page_views(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics visits failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/searches")
+async def analytics_searches(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_searches(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics searches failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
 @app.post("/api/search")
 @limiter.limit("2/minute")
 async def search(request: Request, body: SearchRequest):
@@ -60,9 +129,21 @@ async def search(request: Request, body: SearchRequest):
 
  try:
  packages = await package_search(body.query)
+ except Exception:
+ logger.exception("Package search failed")
+ raise HTTPException(status_code=502, detail="Failed in hybrid search") from None
+
+ try:
+ await record_search(
+ query=body.query,
+ framework=body.framework,
+ priorities=body.priorities,
+ result_count=len(packages),
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ )
  except Exception as e:
- logger.error(f"Package search failed: {e}")
- raise HTTPException(status_code=502, detail="Failed in hybrid search") from e
+ logger.warning(f"Failed to record search event: {e}")
 
  if not packages:
  logger.info("No packages found for query, returning empty response")

backend/app/models.py

@@ -1,3 +1,5 @@
+from datetime import datetime
+
 from pydantic import BaseModel, Field
 
 
@@ -18,3 +20,34 @@ class Package(BaseModel):
 
 class SearchResponse(BaseModel):
  packages: list[Package]
+
+
+class PageView(BaseModel):
+ visited_at: datetime
+ ip_hash: str
+ user_agent: str | None = None
+ referrer: str | None = None
+
+
+class SearchEvent(BaseModel):
+ searched_at: datetime
+ query: str
+ framework: str | None = None
+ priorities: list[str] | None = None
+ result_count: int
+
+
+class TopItem(BaseModel):
+ label: str
+ count: int
+
+
+class AnalyticsSummary(BaseModel):
+ total_visits: int
+ unique_visitors: int
+ total_searches: int
+ visits_last_24h: int
+ searches_last_24h: int
+ top_queries: list[TopItem]
+ top_frameworks: list[TopItem]
+ top_referrers: list[TopItem]

backend/app/search.py

@@ -2,10 +2,11 @@
 import logging
 import os
 
-import asyncpg
 from openai import AsyncOpenAI
 from qdrant_client import AsyncQdrantClient
 
+from app.db import get_pool
+
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
@@ -40,19 +41,6 @@ def get_qdrant_client() -> AsyncQdrantClient:
 COLLECTION_NAME = "npmatch"
 CANDIDATE_LIMIT = 20
 
-_pg_pool: asyncpg.Pool | None = None
-
-
-async def _get_pool() -> asyncpg.Pool:
- global _pg_pool
- if _pg_pool is None:
- _pg_pool = await asyncpg.create_pool(
- dsn=os.environ["DATABASE_CONNECTION_STRING"],
- min_size=1,
- max_size=5,
- )
- return _pg_pool
-
 
 def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
  scores: dict[str, float] = {}
@@ -89,7 +77,7 @@ async def _vector_search(embedding: list[float]) -> list[str]:
 
 
 async def _fts_search(query: str) -> list[str]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  """
  SELECT name,
@@ -115,7 +103,7 @@ def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
 
 
 async def _fetch_metadata(names: list[str]) -> list[dict]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  "SELECT name, description, keywords, version FROM packages WHERE name = ANY($1)",
  names,

.gitignore

@@ -17,3 +17,6 @@ frontend/.openclaude/
 # Build artifacts
 frontend/next-env.d.ts
 CLAUDE 2.md
+
+# Trace logs
+*.log

backend/.env.example

@@ -2,3 +2,4 @@ OPENAI_API_KEY="YOUR_KEY"
 QDRANT_URL=http://qdrant:6333
 QDRANT_CLOUD_API_KEY="YOUR_KEY"
 DATABASE_CONNECTION_STRING=postgresql://npmatch:npmatch@postgres:5432/npmatch
+ANALYTICS_TOKEN="YOUR_TOKEN"

backend/app/analytics.py

@@ -0,0 +1,152 @@
+import hashlib
+import logging
+import os
+from datetime import UTC, datetime, timedelta
+
+from fastapi import Request
+
+from app.db import get_pool
+
+logger = logging.getLogger(__name__)
+
+SEARCH_EVENT_INSERT = """
+INSERT INTO search_events (query, framework, priorities, result_count, ip_hash, user_agent)
+VALUES ($1, $2, $3, $4, $5, $6)
+"""
+
+
+def hash_ip(ip: str) -> str:
+ """SHA-256 hash of the client IP, salted so it isn't reversible."""
+ salt = os.environ.get("ANALYTICS_SALT", "npmatch")
+ return hashlib.sha256(f"{salt}:{ip}".encode()).hexdigest()
+
+
+def client_ip(request: Request) -> str:
+ """Client IP, honoring X-Forwarded-For (set by the Next.js proxy)."""
+ forwarded = request.headers.get("x-forwarded-for")
+ if forwarded:
+ return forwarded.split(",")[0].strip()
+ if request.client:
+ return request.client.host
+ return "unknown"
+
+
+async def record_page_view(*, ip_hash: str, user_agent: str | None, referrer: str | None) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ "INSERT INTO page_views (ip_hash, user_agent, referrer) VALUES ($1, $2, $3)",
+ ip_hash,
+ user_agent,
+ referrer,
+ )
+
+
+async def record_search(
+ *,
+ query: str,
+ framework: str | None,
+ priorities: list[str] | None,
+ result_count: int,
+ ip_hash: str,
+ user_agent: str | None,
+) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ SEARCH_EVENT_INSERT,
+ query,
+ framework,
+ ", ".join(priorities) if priorities else None,
+ result_count,
+ ip_hash,
+ user_agent,
+ )
+
+
+async def get_analytics_summary() -> dict:
+ pool = await get_pool()
+ cutoff = datetime.now(UTC) - timedelta(hours=24)
+
+ row = await pool.fetchrow(
+ """
+ SELECT
+ (SELECT count(*) FROM page_views) AS total_visits,
+ (SELECT count(DISTINCT ip_hash) FROM page_views) AS unique_visitors,
+ (SELECT count(*) FROM search_events) AS total_searches,
+ (SELECT count(*) FROM page_views WHERE visited_at >= $1) AS visits_last_24h,
+ (SELECT count(*) FROM search_events WHERE searched_at >= $1) AS searches_last_24h
+ """,
+ cutoff,
+ )
+
+ top_queries = await pool.fetch(
+ """
+ SELECT query, count(*) AS count
+ FROM search_events
+ GROUP BY query
+ ORDER BY count DESC, query ASC
+ LIMIT 10
+ """
+ )
+ top_frameworks = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(framework, ''), 'any') AS framework, count(*) AS count
+ FROM search_events
+ GROUP BY COALESCE(NULLIF(framework, ''), 'any')
+ ORDER BY count DESC, framework ASC
+ LIMIT 10
+ """
+ )
+ top_referrers = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(referrer, ''), '(direct)') AS referrer, count(*) AS count
+ FROM page_views
+ GROUP BY COALESCE(NULLIF(referrer, ''), '(direct)')
+ ORDER BY count DESC, referrer ASC
+ LIMIT 10
+ """
+ )
+
+ return {
+ "total_visits": row["total_visits"],
+ "unique_visitors": row["unique_visitors"],
+ "total_searches": row["total_searches"],
+ "visits_last_24h": row["visits_last_24h"],
+ "searches_last_24h": row["searches_last_24h"],
+ "top_queries": [{"label": r["query"], "count": r["count"]} for r in top_queries],
+ "top_frameworks": [{"label": r["framework"], "count": r["count"]} for r in top_frameworks],
+ "top_referrers": [{"label": r["referrer"], "count": r["count"]} for r in top_referrers],
+ }
+
+
+async def list_page_views(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT visited_at, ip_hash, user_agent, referrer
+ FROM page_views
+ ORDER BY visited_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ return [dict(r) for r in rows]
+
+
+async def list_searches(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT searched_at, query, framework, priorities, result_count
+ FROM search_events
+ ORDER BY searched_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ out = []
+ for row in rows:
+ item = dict(row)
+ priorities = item["priorities"]
+ item["priorities"] = [p.strip() for p in priorities.split(",")] if priorities else None
+ out.append(item)
+ return out

backend/app/db.py

@@ -0,0 +1,19 @@
+import os
+
+import asyncpg
+
+_pg_pool: asyncpg.Pool | None = None
+
+
+async def get_pool() -> asyncpg.Pool:
+ """Lazy initialization of the shared asyncpg pool."""
+ global _pg_pool
+
+ if _pg_pool is None:
+ _pg_pool = await asyncpg.create_pool(
+ dsn=os.environ["DATABASE_CONNECTION_STRING"],
+ min_size=1,
+ max_size=5,
+ )
+
+ return _pg_pool

backend/app/main.py

@@ -10,6 +10,15 @@
 from slowapi.util import get_remote_address
 
 import app.env
+from app.analytics import (
+ client_ip,
+ get_analytics_summary,
+ hash_ip,
+ list_page_views,
+ list_searches,
+ record_page_view,
+ record_search,
+)
 from app.llm import stream_response
 from app.models import SearchRequest
 from app.search import package_search
@@ -50,6 +59,66 @@ async def health():
  return {"status": "ok"}
 
 
+def _require_analytics_token(request: Request) -> None:
+ expected = os.environ.get("ANALYTICS_TOKEN")
+ if not expected:
+ raise HTTPException(status_code=503, detail="Analytics token not configured")
+ if request.headers.get("x-analytics-token") != expected:
+ raise HTTPException(status_code=401, detail="Unauthorized")
+
+
+@app.post("/api/track/pageview")
+@limiter.limit("120/minute")
+async def track_pageview(request: Request):
+ referrer = None
+ try:
+ body = await request.json()
+ referrer = body.get("referrer")
+ except Exception:
+ pass
+
+ try:
+ await record_page_view(
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ referrer=referrer or request.headers.get("referer"),
+ )
+ except Exception as e:
+ logger.warning(f"Failed to record page view: {e}")
+
+ return {"ok": True}
+
+
+@app.get("/api/analytics/summary")
+async def analytics_summary(request: Request):
+ _require_analytics_token(request)
+ try:
+ return await get_analytics_summary()
+ except Exception:
+ logger.exception("Analytics summary failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/visits")
+async def analytics_visits(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_page_views(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics visits failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/searches")
+async def analytics_searches(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_searches(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics searches failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
 @app.post("/api/search")
 @limiter.limit("2/minute")
 async def search(request: Request, body: SearchRequest):
@@ -60,9 +129,21 @@ async def search(request: Request, body: SearchRequest):
 
  try:
  packages = await package_search(body.query)
+ except Exception:
+ logger.exception("Package search failed")
+ raise HTTPException(status_code=502, detail="Failed in hybrid search") from None
+
+ try:
+ await record_search(
+ query=body.query,
+ framework=body.framework,
+ priorities=body.priorities,
+ result_count=len(packages),
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ )
  except Exception as e:
- logger.error(f"Package search failed: {e}")
- raise HTTPException(status_code=502, detail="Failed in hybrid search") from e
+ logger.warning(f"Failed to record search event: {e}")
 
  if not packages:
  logger.info("No packages found for query, returning empty response")

backend/app/models.py

@@ -1,3 +1,5 @@
+from datetime import datetime
+
 from pydantic import BaseModel, Field
 
 
@@ -18,3 +20,34 @@ class Package(BaseModel):
 
 class SearchResponse(BaseModel):
  packages: list[Package]
+
+
+class PageView(BaseModel):
+ visited_at: datetime
+ ip_hash: str
+ user_agent: str | None = None
+ referrer: str | None = None
+
+
+class SearchEvent(BaseModel):
+ searched_at: datetime
+ query: str
+ framework: str | None = None
+ priorities: list[str] | None = None
+ result_count: int
+
+
+class TopItem(BaseModel):
+ label: str
+ count: int
+
+
+class AnalyticsSummary(BaseModel):
+ total_visits: int
+ unique_visitors: int
+ total_searches: int
+ visits_last_24h: int
+ searches_last_24h: int
+ top_queries: list[TopItem]
+ top_frameworks: list[TopItem]
+ top_referrers: list[TopItem]

backend/app/search.py

@@ -2,10 +2,11 @@
 import logging
 import os
 
-import asyncpg
 from openai import AsyncOpenAI
 from qdrant_client import AsyncQdrantClient
 
+from app.db import get_pool
+
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
@@ -40,19 +41,6 @@ def get_qdrant_client() -> AsyncQdrantClient:
 COLLECTION_NAME = "npmatch"
 CANDIDATE_LIMIT = 20
 
-_pg_pool: asyncpg.Pool | None = None
-
-
-async def _get_pool() -> asyncpg.Pool:
- global _pg_pool
- if _pg_pool is None:
- _pg_pool = await asyncpg.create_pool(
- dsn=os.environ["DATABASE_CONNECTION_STRING"],
- min_size=1,
- max_size=5,
- )
- return _pg_pool
-
 
 def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
  scores: dict[str, float] = {}
@@ -89,7 +77,7 @@ async def _vector_search(embedding: list[float]) -> list[str]:
 
 
 async def _fts_search(query: str) -> list[str]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  """
  SELECT name,
@@ -115,7 +103,7 @@ def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
 
 
 async def _fetch_metadata(names: list[str]) -> list[dict]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  "SELECT name, description, keywords, version FROM packages WHERE name = ANY($1)",
  names,

.gitignore

@@ -17,3 +17,6 @@ frontend/.openclaude/
 # Build artifacts
 frontend/next-env.d.ts
 CLAUDE 2.md
+
+# Trace logs
+*.log

backend/.env.example

@@ -2,3 +2,4 @@ OPENAI_API_KEY="YOUR_KEY"
 QDRANT_URL=http://qdrant:6333
 QDRANT_CLOUD_API_KEY="YOUR_KEY"
 DATABASE_CONNECTION_STRING=postgresql://npmatch:npmatch@postgres:5432/npmatch
+ANALYTICS_TOKEN="YOUR_TOKEN"

backend/app/analytics.py

@@ -0,0 +1,152 @@
+import hashlib
+import logging
+import os
+from datetime import UTC, datetime, timedelta
+
+from fastapi import Request
+
+from app.db import get_pool
+
+logger = logging.getLogger(__name__)
+
+SEARCH_EVENT_INSERT = """
+INSERT INTO search_events (query, framework, priorities, result_count, ip_hash, user_agent)
+VALUES ($1, $2, $3, $4, $5, $6)
+"""
+
+
+def hash_ip(ip: str) -> str:
+ """SHA-256 hash of the client IP, salted so it isn't reversible."""
+ salt = os.environ.get("ANALYTICS_SALT", "npmatch")
+ return hashlib.sha256(f"{salt}:{ip}".encode()).hexdigest()
+
+
+def client_ip(request: Request) -> str:
+ """Client IP, honoring X-Forwarded-For (set by the Next.js proxy)."""
+ forwarded = request.headers.get("x-forwarded-for")
+ if forwarded:
+ return forwarded.split(",")[0].strip()
+ if request.client:
+ return request.client.host
+ return "unknown"
+
+
+async def record_page_view(*, ip_hash: str, user_agent: str | None, referrer: str | None) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ "INSERT INTO page_views (ip_hash, user_agent, referrer) VALUES ($1, $2, $3)",
+ ip_hash,
+ user_agent,
+ referrer,
+ )
+
+
+async def record_search(
+ *,
+ query: str,
+ framework: str | None,
+ priorities: list[str] | None,
+ result_count: int,
+ ip_hash: str,
+ user_agent: str | None,
+) -> None:
+ pool = await get_pool()
+ await pool.execute(
+ SEARCH_EVENT_INSERT,
+ query,
+ framework,
+ ", ".join(priorities) if priorities else None,
+ result_count,
+ ip_hash,
+ user_agent,
+ )
+
+
+async def get_analytics_summary() -> dict:
+ pool = await get_pool()
+ cutoff = datetime.now(UTC) - timedelta(hours=24)
+
+ row = await pool.fetchrow(
+ """
+ SELECT
+ (SELECT count(*) FROM page_views) AS total_visits,
+ (SELECT count(DISTINCT ip_hash) FROM page_views) AS unique_visitors,
+ (SELECT count(*) FROM search_events) AS total_searches,
+ (SELECT count(*) FROM page_views WHERE visited_at >= $1) AS visits_last_24h,
+ (SELECT count(*) FROM search_events WHERE searched_at >= $1) AS searches_last_24h
+ """,
+ cutoff,
+ )
+
+ top_queries = await pool.fetch(
+ """
+ SELECT query, count(*) AS count
+ FROM search_events
+ GROUP BY query
+ ORDER BY count DESC, query ASC
+ LIMIT 10
+ """
+ )
+ top_frameworks = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(framework, ''), 'any') AS framework, count(*) AS count
+ FROM search_events
+ GROUP BY COALESCE(NULLIF(framework, ''), 'any')
+ ORDER BY count DESC, framework ASC
+ LIMIT 10
+ """
+ )
+ top_referrers = await pool.fetch(
+ """
+ SELECT COALESCE(NULLIF(referrer, ''), '(direct)') AS referrer, count(*) AS count
+ FROM page_views
+ GROUP BY COALESCE(NULLIF(referrer, ''), '(direct)')
+ ORDER BY count DESC, referrer ASC
+ LIMIT 10
+ """
+ )
+
+ return {
+ "total_visits": row["total_visits"],
+ "unique_visitors": row["unique_visitors"],
+ "total_searches": row["total_searches"],
+ "visits_last_24h": row["visits_last_24h"],
+ "searches_last_24h": row["searches_last_24h"],
+ "top_queries": [{"label": r["query"], "count": r["count"]} for r in top_queries],
+ "top_frameworks": [{"label": r["framework"], "count": r["count"]} for r in top_frameworks],
+ "top_referrers": [{"label": r["referrer"], "count": r["count"]} for r in top_referrers],
+ }
+
+
+async def list_page_views(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT visited_at, ip_hash, user_agent, referrer
+ FROM page_views
+ ORDER BY visited_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ return [dict(r) for r in rows]
+
+
+async def list_searches(limit: int = 50) -> list[dict]:
+ pool = await get_pool()
+ rows = await pool.fetch(
+ """
+ SELECT searched_at, query, framework, priorities, result_count
+ FROM search_events
+ ORDER BY searched_at DESC
+ LIMIT $1
+ """,
+ limit,
+ )
+ out = []
+ for row in rows:
+ item = dict(row)
+ priorities = item["priorities"]
+ item["priorities"] = [p.strip() for p in priorities.split(",")] if priorities else None
+ out.append(item)
+ return out

backend/app/db.py

@@ -0,0 +1,19 @@
+import os
+
+import asyncpg
+
+_pg_pool: asyncpg.Pool | None = None
+
+
+async def get_pool() -> asyncpg.Pool:
+ """Lazy initialization of the shared asyncpg pool."""
+ global _pg_pool
+
+ if _pg_pool is None:
+ _pg_pool = await asyncpg.create_pool(
+ dsn=os.environ["DATABASE_CONNECTION_STRING"],
+ min_size=1,
+ max_size=5,
+ )
+
+ return _pg_pool

backend/app/main.py

@@ -10,6 +10,15 @@
 from slowapi.util import get_remote_address
 
 import app.env
+from app.analytics import (
+ client_ip,
+ get_analytics_summary,
+ hash_ip,
+ list_page_views,
+ list_searches,
+ record_page_view,
+ record_search,
+)
 from app.llm import stream_response
 from app.models import SearchRequest
 from app.search import package_search
@@ -50,6 +59,66 @@ async def health():
  return {"status": "ok"}
 
 
+def _require_analytics_token(request: Request) -> None:
+ expected = os.environ.get("ANALYTICS_TOKEN")
+ if not expected:
+ raise HTTPException(status_code=503, detail="Analytics token not configured")
+ if request.headers.get("x-analytics-token") != expected:
+ raise HTTPException(status_code=401, detail="Unauthorized")
+
+
+@app.post("/api/track/pageview")
+@limiter.limit("120/minute")
+async def track_pageview(request: Request):
+ referrer = None
+ try:
+ body = await request.json()
+ referrer = body.get("referrer")
+ except Exception:
+ pass
+
+ try:
+ await record_page_view(
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ referrer=referrer or request.headers.get("referer"),
+ )
+ except Exception as e:
+ logger.warning(f"Failed to record page view: {e}")
+
+ return {"ok": True}
+
+
+@app.get("/api/analytics/summary")
+async def analytics_summary(request: Request):
+ _require_analytics_token(request)
+ try:
+ return await get_analytics_summary()
+ except Exception:
+ logger.exception("Analytics summary failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/visits")
+async def analytics_visits(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_page_views(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics visits failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
+@app.get("/api/analytics/searches")
+async def analytics_searches(request: Request, limit: int = 50):
+ _require_analytics_token(request)
+ try:
+ return await list_searches(limit=min(limit, 200))
+ except Exception:
+ logger.exception("Analytics searches failed")
+ raise HTTPException(status_code=502, detail="Analytics query failed") from None
+
+
 @app.post("/api/search")
 @limiter.limit("2/minute")
 async def search(request: Request, body: SearchRequest):
@@ -60,9 +129,21 @@ async def search(request: Request, body: SearchRequest):
 
  try:
  packages = await package_search(body.query)
+ except Exception:
+ logger.exception("Package search failed")
+ raise HTTPException(status_code=502, detail="Failed in hybrid search") from None
+
+ try:
+ await record_search(
+ query=body.query,
+ framework=body.framework,
+ priorities=body.priorities,
+ result_count=len(packages),
+ ip_hash=hash_ip(client_ip(request)),
+ user_agent=request.headers.get("user-agent"),
+ )
  except Exception as e:
- logger.error(f"Package search failed: {e}")
- raise HTTPException(status_code=502, detail="Failed in hybrid search") from e
+ logger.warning(f"Failed to record search event: {e}")
 
  if not packages:
  logger.info("No packages found for query, returning empty response")

backend/app/models.py

@@ -1,3 +1,5 @@
+from datetime import datetime
+
 from pydantic import BaseModel, Field
 
 
@@ -18,3 +20,34 @@ class Package(BaseModel):
 
 class SearchResponse(BaseModel):
  packages: list[Package]
+
+
+class PageView(BaseModel):
+ visited_at: datetime
+ ip_hash: str
+ user_agent: str | None = None
+ referrer: str | None = None
+
+
+class SearchEvent(BaseModel):
+ searched_at: datetime
+ query: str
+ framework: str | None = None
+ priorities: list[str] | None = None
+ result_count: int
+
+
+class TopItem(BaseModel):
+ label: str
+ count: int
+
+
+class AnalyticsSummary(BaseModel):
+ total_visits: int
+ unique_visitors: int
+ total_searches: int
+ visits_last_24h: int
+ searches_last_24h: int
+ top_queries: list[TopItem]
+ top_frameworks: list[TopItem]
+ top_referrers: list[TopItem]

backend/app/search.py

@@ -2,10 +2,11 @@
 import logging
 import os
 
-import asyncpg
 from openai import AsyncOpenAI
 from qdrant_client import AsyncQdrantClient
 
+from app.db import get_pool
+
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
@@ -40,19 +41,6 @@ def get_qdrant_client() -> AsyncQdrantClient:
 COLLECTION_NAME = "npmatch"
 CANDIDATE_LIMIT = 20
 
-_pg_pool: asyncpg.Pool | None = None
-
-
-async def _get_pool() -> asyncpg.Pool:
- global _pg_pool
- if _pg_pool is None:
- _pg_pool = await asyncpg.create_pool(
- dsn=os.environ["DATABASE_CONNECTION_STRING"],
- min_size=1,
- max_size=5,
- )
- return _pg_pool
-
 
 def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
  scores: dict[str, float] = {}
@@ -89,7 +77,7 @@ async def _vector_search(embedding: list[float]) -> list[str]:
 
 
 async def _fts_search(query: str) -> list[str]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  """
  SELECT name,
@@ -115,7 +103,7 @@ def _rrf(rankings: list[list[str]], k: int = 60) -> list[str]:
 
 
 async def _fetch_metadata(names: list[str]) -> list[dict]:
- pool = await _get_pool()
+ pool = await get_pool()
  rows = await pool.fetch(
  "SELECT name, description, keywords, version FROM packages WHERE name = ANY($1)",
  names,