Implemented the admin metrics feature end to end

backend/app/main.py

@@ -92,11 +92,13 @@ from app.routes.auth import router as auth_router
 from app.routes.documents import router as documents_router
 from app.routes.chat import router as chat_router
 from app.routes.github import router as github_router
+from app.routes.admin import router as admin_router
 
 app.include_router(auth_router, prefix="/api/v1")
 app.include_router(documents_router, prefix="/api/v1")
 app.include_router(chat_router, prefix="/api/v1")
 app.include_router(github_router, prefix="/api/v1")
+app.include_router(admin_router, prefix="/api/v1")
 
 
 # ── Health Check ─────────────────────────────────────

backend/app/metrics.py

@@ -0,0 +1,33 @@
+"""
+Runtime metrics helpers for lightweight operational statistics.
+"""
+from threading import Lock
+
+
+_metrics_lock = Lock()
+_query_count = 0
+_query_response_time_total_ms = 0.0
+
+
+def record_query_response_time(duration_seconds: float) -> None:
+    """Record one completed query response duration."""
+    global _query_count, _query_response_time_total_ms
+
+    duration_ms = max(duration_seconds, 0) * 1000
+    with _metrics_lock:
+        _query_count += 1
+        _query_response_time_total_ms += duration_ms
+
+
+def get_query_metrics() -> dict[str, float | int]:
+    """Return aggregate query metrics for the current process lifetime."""
+    with _metrics_lock:
+        average_ms = (
+            _query_response_time_total_ms / _query_count
+            if _query_count
+            else 0.0
+        )
+        return {
+            "query_count": _query_count,
+            "average_query_response_time_ms": round(average_ms, 2),
+        }

backend/app/rag/vectorstore.py

@@ -4,11 +4,7 @@ Per-user collections for data isolation.
 """
 import logging
 from typing import List, Dict, Any, Optional
-import chromadb
-from chromadb.config import Settings as ChromaSettings
 from app.config import get_settings
-from app.rag.embeddings import get_embedding_model
-from app.rag.vision import generate_captions_for_chunks
 
 logger = logging.getLogger(__name__)
 settings = get_settings()
@@ -17,12 +13,15 @@ settings = get_settings()
 _chroma_client = None
 
 
-def get_chroma_client() -> chromadb.ClientAPI:
+def get_chroma_client():
     """Get or create persistent ChromaDB client."""
     global _chroma_client
 
     if _chroma_client is None:
         import os
+        import chromadb
+        from chromadb.config import Settings as ChromaSettings
+
         os.makedirs(settings.CHROMA_PERSIST_DIR, exist_ok=True)
 
         _chroma_client = chromadb.PersistentClient(
@@ -58,11 +57,15 @@ def store_chunks(
 
     # Generate captions for any extracted images before embedding
     try:
+        from app.rag.vision import generate_captions_for_chunks
+
         generate_captions_for_chunks(chunks)
     except Exception as e:
         logger.warning(f"Could not generate image captions: {e}")
 
     client = get_chroma_client()
+    from app.rag.embeddings import get_embedding_model
+
     embedding_model = get_embedding_model()
 
     collection_name = get_collection_name(user_id)

backend/app/routes/admin.py

@@ -0,0 +1,73 @@
+"""
+Admin-only operational statistics routes.
+"""
+import shutil
+from pathlib import Path
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import func
+from sqlalchemy.orm import Session
+
+from app.auth import get_admin_user
+from app.config import get_settings
+from app.database import get_db
+from app.metrics import get_query_metrics
+from app.models import Document, User
+from app.schemas import AdminStatsResponse, DiskUsageResponse
+
+router = APIRouter(prefix="/admin", tags=["Admin"])
+settings = get_settings()
+
+
+def _directory_size(path: Path) -> int:
+    if not path.exists():
+        return 0
+
+    total = 0
+    for item in path.rglob("*"):
+        if item.is_file():
+            try:
+                total += item.stat().st_size
+            except OSError:
+                continue
+    return total
+
+
+@router.get("/stats", response_model=AdminStatsResponse)
+def get_admin_stats(
+    _admin: User = Depends(get_admin_user),
+    db: Session = Depends(get_db),
+):
+    """Return aggregate system statistics for administrators."""
+    upload_dir = Path(settings.UPLOAD_DIR).resolve()
+    upload_dir.mkdir(parents=True, exist_ok=True)
+
+    disk_usage = shutil.disk_usage(upload_dir)
+    used_percent = (
+        round((disk_usage.used / disk_usage.total) * 100, 2)
+        if disk_usage.total
+        else 0.0
+    )
+    query_metrics = get_query_metrics()
+
+    total_pdfs_uploaded = (
+        db.query(Document)
+        .filter(func.lower(Document.original_name).like("%.pdf"))
+        .count()
+    )
+
+    return AdminStatsResponse(
+        total_users=db.query(User).count(),
+        total_pdfs_uploaded=total_pdfs_uploaded,
+        average_query_response_time_ms=float(
+            query_metrics["average_query_response_time_ms"]
+        ),
+        query_count=int(query_metrics["query_count"]),
+        disk_space_usage=DiskUsageResponse(
+            total_bytes=disk_usage.total,
+            used_bytes=disk_usage.used,
+            free_bytes=disk_usage.free,
+            usage_percent=used_percent,
+            upload_dir_bytes=_directory_size(upload_dir),
+        ),
+    )

backend/app/routes/chat.py

@@ -3,6 +3,7 @@ Chat routes — ask questions with RAG, stream responses via SSE, manage history
 """
 import html
 import json
+import time
 from datetime import datetime
 from io import BytesIO
 import logging
@@ -18,6 +19,7 @@ from sqlalchemy.orm import Session
 
 from app.database import get_db
 from app.models import User, ChatMessage, Document
+from app.metrics import record_query_response_time
 from app.schemas import ChatRequest, ChatResponse, ChatMessageResponse, ChatHistoryResponse, SourceChunk
 from app.auth import get_current_user
 from app.rag.agent import generate_answer, generate_answer_stream
@@ -63,38 +65,42 @@ def ask_question(
         HTTPException: 400 if the document exists but its status is not
             "ready" (e.g., still processing or failed).
     """
-    # Validate document exists if specified
-    if payload.document_id:
-        doc = db.query(Document).filter(
-            Document.id == payload.document_id,
-            Document.user_id == user.id,
-        ).first()
-
-        if not doc:
-            raise HTTPException(status_code=404, detail="Document not found")
-
-        if doc.status != "ready":
-            raise HTTPException(
-                status_code=400,
-                detail=f"Document is still {doc.status}. Please wait for processing to complete.",
-            )
-
-    # Generate answer
-    result = generate_answer(
-        question=payload.question,
-        user_id=user.id,
-        document_id=payload.document_id,
-    )
+    started_at = time.perf_counter()
+    try:
+        # Validate document exists if specified
+        if payload.document_id:
+            doc = db.query(Document).filter(
+                Document.id == payload.document_id,
+                Document.user_id == user.id,
+            ).first()
+
+            if not doc:
+                raise HTTPException(status_code=404, detail="Document not found")
+
+            if doc.status != "ready":
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Document is still {doc.status}. Please wait for processing to complete.",
+                )
+
+        # Generate answer
+        result = generate_answer(
+            question=payload.question,
+            user_id=user.id,
+            document_id=payload.document_id,
+        )
 
-    # Save to chat history
-    _save_message(db, user.id, payload.document_id, "user", payload.question)
-    _save_message(db, user.id, payload.document_id, "assistant", result["answer"], result["sources"])
+        # Save to chat history
+        _save_message(db, user.id, payload.document_id, "user", payload.question)
+        _save_message(db, user.id, payload.document_id, "assistant", result["answer"], result["sources"])
 
-    return ChatResponse(
-        answer=result["answer"],
-        sources=[SourceChunk(**s) for s in result["sources"]],
-        document_id=payload.document_id,
-    )
+        return ChatResponse(
+            answer=result["answer"],
+            sources=[SourceChunk(**s) for s in result["sources"]],
+            document_id=payload.document_id,
+        )
+    finally:
+        record_query_response_time(time.perf_counter() - started_at)
 
 
 @router.post("/ask/stream")
@@ -156,6 +162,8 @@ def ask_question_stream(
                 detail=f"Document is still {doc.status}. Please wait for processing to complete.",
             )
 
+    started_at = time.perf_counter()
+
     # Save user message immediately
     _save_message(db, user.id, payload.document_id, "user", payload.question)
 
@@ -164,31 +172,34 @@ def ask_question_stream(
         full_answer = ""
         sources = []
 
-        for chunk in generate_answer_stream(
-            question=payload.question,
-            user_id=user.id,
-            document_id=payload.document_id,
-        ):
-            yield chunk
-
-            # Parse to accumulate full answer for history
-            try:
-                if chunk.startswith("data: "):
-                    data = json.loads(chunk[6:].strip())
-                    if data.get("type") == "token":
-                        full_answer += data.get("data", "")
-                    elif data.get("type") == "sources":
-                        sources = data.get("data", [])
-            except Exception:
-                pass
-
-        # Save assistant response to history
-        from app.database import SessionLocal
-        save_db = SessionLocal()
         try:
-            _save_message(save_db, user.id, payload.document_id, "assistant", full_answer, sources)
+            for chunk in generate_answer_stream(
+                question=payload.question,
+                user_id=user.id,
+                document_id=payload.document_id,
+            ):
+                yield chunk
+
+                # Parse to accumulate full answer for history
+                try:
+                    if chunk.startswith("data: "):
+                        data = json.loads(chunk[6:].strip())
+                        if data.get("type") == "token":
+                            full_answer += data.get("data", "")
+                        elif data.get("type") == "sources":
+                            sources = data.get("data", [])
+                except Exception:
+                    pass
+
+            # Save assistant response to history
+            from app.database import SessionLocal
+            save_db = SessionLocal()
+            try:
+                _save_message(save_db, user.id, payload.document_id, "assistant", full_answer, sources)
+            finally:
+                save_db.close()
         finally:
-            save_db.close()
+            record_query_response_time(time.perf_counter() - started_at)
 
     return StreamingResponse(
         event_stream(),

backend/app/schemas.py

@@ -99,6 +99,24 @@ class DocumentListResponse(BaseModel):
     pages: int
 
 
+# Admin
+
+class DiskUsageResponse(BaseModel):
+    total_bytes: int
+    used_bytes: int
+    free_bytes: int
+    usage_percent: float
+    upload_dir_bytes: int
+
+
+class AdminStatsResponse(BaseModel):
+    total_users: int
+    total_pdfs_uploaded: int
+    average_query_response_time_ms: float
+    query_count: int
+    disk_space_usage: DiskUsageResponse
+
+
 # ── Chat ─────────────────────────────────────────────
 
 class ChatRequest(BaseModel):

backend/tests/test_admin.py

@@ -0,0 +1,65 @@
+from app.auth import create_access_token, hash_password
+from app.metrics import record_query_response_time
+from app.models import Document, User
+
+
+def test_admin_stats_requires_admin(client, auth_headers):
+    response = client.get("/api/v1/admin/stats", headers=auth_headers)
+
+    assert response.status_code == 403
+    assert response.json()["detail"] == "Admin access required"
+
+
+def test_admin_stats_returns_aggregate_metrics(client, db_session):
+    admin = User(
+        username="admin",
+        email="admin@example.com",
+        hashed_password=hash_password("password123"),
+        is_admin=True,
+    )
+    regular = User(
+        username="regular",
+        email="regular@example.com",
+        hashed_password=hash_password("password123"),
+    )
+    db_session.add_all([admin, regular])
+    db_session.commit()
+    db_session.refresh(admin)
+    db_session.refresh(regular)
+
+    db_session.add_all(
+        [
+            Document(
+                user_id=regular.id,
+                filename="first.pdf",
+                original_name="first.pdf",
+                file_size=100,
+                status="ready",
+            ),
+            Document(
+                user_id=regular.id,
+                filename="notes.txt",
+                original_name="notes.txt",
+                file_size=50,
+                status="ready",
+            ),
+        ]
+    )
+    db_session.commit()
+
+    record_query_response_time(0.25)
+
+    token = create_access_token(admin.id)
+    response = client.get(
+        "/api/v1/admin/stats",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["total_users"] == 2
+    assert payload["total_pdfs_uploaded"] == 1
+    assert payload["average_query_response_time_ms"] > 0
+    assert payload["query_count"] >= 1
+    assert payload["disk_space_usage"]["total_bytes"] > 0
+    assert payload["disk_space_usage"]["usage_percent"] >= 0

frontend/src/app/admin/page.tsx

@@ -0,0 +1,277 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useRouter } from "next/navigation";
+import {
+  ArrowLeft,
+  Clock3,
+  Database,
+  FileText,
+  HardDrive,
+  RefreshCw,
+  Users,
+} from "lucide-react";
+
+import { api, CONNECTION_ERROR_MESSAGE } from "@/lib/api";
+import { useAuth } from "@/lib/auth";
+import { Button } from "@/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { Progress } from "@/components/ui/progress";
+import { Skeleton } from "@/components/ui/skeleton";
+
+interface AdminStats {
+  total_users: number;
+  total_pdfs_uploaded: number;
+  average_query_response_time_ms: number;
+  query_count: number;
+  disk_space_usage: {
+    total_bytes: number;
+    used_bytes: number;
+    free_bytes: number;
+    usage_percent: number;
+    upload_dir_bytes: number;
+  };
+}
+
+const formatBytes = (bytes: number) => {
+  if (!Number.isFinite(bytes) || bytes <= 0) return "0 B";
+
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const index = Math.min(
+    Math.floor(Math.log(bytes) / Math.log(1024)),
+    units.length - 1
+  );
+
+  return `${(bytes / 1024 ** index).toFixed(index === 0 ? 0 : 1)} ${units[index]}`;
+};
+
+const formatTime = (milliseconds: number) => {
+  if (milliseconds >= 1000) return `${(milliseconds / 1000).toFixed(2)} s`;
+  return `${Math.round(milliseconds)} ms`;
+};
+
+function MetricCard({
+  icon: Icon,
+  label,
+  value,
+  detail,
+}: {
+  icon: typeof Users;
+  label: string;
+  value: string;
+  detail: string;
+}) {
+  return (
+    <Card className="min-h-36">
+      <CardHeader className="grid-cols-[1fr_auto]">
+        <div>
+          <CardDescription>{label}</CardDescription>
+          <CardTitle className="mt-2 text-3xl tabular-nums">{value}</CardTitle>
+        </div>
+        <div className="flex h-9 w-9 items-center justify-center rounded-lg bg-primary/15 text-primary">
+          <Icon className="h-4 w-4" />
+        </div>
+      </CardHeader>
+      <CardContent>
+        <p className="text-sm text-muted-foreground">{detail}</p>
+      </CardContent>
+    </Card>
+  );
+}
+
+function AdminSkeleton() {
+  return (
+    <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
+      {[1, 2, 3, 4].map((item) => (
+        <Card key={item} className="min-h-36">
+          <CardHeader>
+            <Skeleton className="h-4 w-28" />
+            <Skeleton className="h-8 w-20" />
+          </CardHeader>
+          <CardContent>
+            <Skeleton className="h-4 w-36" />
+          </CardContent>
+        </Card>
+      ))}
+    </div>
+  );
+}
+
+export default function AdminPage() {
+  const { user, loading } = useAuth();
+  const router = useRouter();
+  const [stats, setStats] = useState<AdminStats | null>(null);
+  const [statsLoading, setStatsLoading] = useState(true);
+  const [error, setError] = useState("");
+  const [lastUpdated, setLastUpdated] = useState<Date | null>(null);
+
+  useEffect(() => {
+    if (loading) return;
+    if (!user) router.replace("/login");
+    else if (!user.is_admin) router.replace("/dashboard");
+  }, [loading, router, user]);
+
+  const loadStats = useCallback(async () => {
+    try {
+      setStatsLoading(true);
+      const data = await api.get<AdminStats>("/api/v1/admin/stats");
+      setStats(data);
+      setLastUpdated(new Date());
+      setError("");
+    } catch (err) {
+      const message =
+        err instanceof Error ? err.message : CONNECTION_ERROR_MESSAGE;
+      setError(message);
+    } finally {
+      setStatsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!user?.is_admin) return;
+
+    const initialLoad = window.setTimeout(() => void loadStats(), 0);
+    const interval = window.setInterval(() => void loadStats(), 10000);
+
+    return () => {
+      window.clearTimeout(initialLoad);
+      window.clearInterval(interval);
+    };
+  }, [loadStats, user?.is_admin]);
+
+  const diskDetail = useMemo(() => {
+    if (!stats) return "";
+    const disk = stats.disk_space_usage;
+    return `${formatBytes(disk.used_bytes)} used of ${formatBytes(disk.total_bytes)}`;
+  }, [stats]);
+
+  if (loading || !user || !user.is_admin) {
+    return (
+      <div className="min-h-screen flex items-center justify-center">
+        <div className="animate-pulse-glow w-12 h-12 rounded-full bg-primary/20" />
+      </div>
+    );
+  }
+
+  return (
+    <div className="min-h-screen bg-background">
+      <header className="sticky top-0 z-40 flex h-14 items-center justify-between border-b border-border/50 bg-card/50 px-4 backdrop-blur-md">
+        <div className="flex items-center gap-3">
+          <Button
+            variant="ghost"
+            size="icon"
+            onClick={() => router.push("/dashboard")}
+            title="Back to dashboard"
+          >
+            <ArrowLeft className="h-4 w-4" />
+          </Button>
+          <div className="flex items-center gap-2">
+            <div className="flex h-7 w-7 items-center justify-center rounded-lg bg-primary/15">
+              <Database className="h-4 w-4 text-primary" />
+            </div>
+            <span className="text-sm font-semibold">Admin Metrics</span>
+          </div>
+        </div>
+
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={() => void loadStats()}
+          disabled={statsLoading}
+        >
+          <RefreshCw className={statsLoading ? "h-4 w-4 animate-spin" : "h-4 w-4"} />
+          Refresh
+        </Button>
+      </header>
+
+      <main className="mx-auto flex w-full max-w-6xl flex-col gap-6 px-4 py-6">
+        <div className="flex flex-col gap-1">
+          <h1 className="text-2xl font-semibold tracking-normal">System overview</h1>
+          <p className="text-sm text-muted-foreground">
+            {lastUpdated
+              ? `Last updated ${lastUpdated.toLocaleTimeString()}`
+              : "Waiting for live metrics"}
+          </p>
+        </div>
+
+        {error && (
+          <div
+            role="alert"
+            className="rounded-lg border border-destructive/30 bg-destructive/10 px-4 py-3 text-sm text-destructive"
+          >
+            {error}
+          </div>
+        )}
+
+        {statsLoading && !stats ? (
+          <AdminSkeleton />
+        ) : stats ? (
+          <>
+            <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
+              <MetricCard
+                icon={Users}
+                label="Total users"
+                value={stats.total_users.toLocaleString()}
+                detail="Registered accounts"
+              />
+              <MetricCard
+                icon={FileText}
+                label="PDFs uploaded"
+                value={stats.total_pdfs_uploaded.toLocaleString()}
+                detail="All uploaded PDF records"
+              />
+              <MetricCard
+                icon={Clock3}
+                label="Avg response time"
+                value={formatTime(stats.average_query_response_time_ms)}
+                detail={`${stats.query_count.toLocaleString()} measured queries`}
+              />
+              <MetricCard
+                icon={HardDrive}
+                label="Upload storage"
+                value={formatBytes(stats.disk_space_usage.upload_dir_bytes)}
+                detail="Files in the upload directory"
+              />
+            </div>
+
+            <Card>
+              <CardHeader>
+                <CardTitle>Disk space usage</CardTitle>
+                <CardDescription>{diskDetail}</CardDescription>
+              </CardHeader>
+              <CardContent className="space-y-4">
+                <Progress value={stats.disk_space_usage.usage_percent} />
+                <div className="grid gap-3 text-sm sm:grid-cols-3">
+                  <div>
+                    <p className="text-muted-foreground">Used</p>
+                    <p className="font-medium tabular-nums">
+                      {formatBytes(stats.disk_space_usage.used_bytes)}
+                    </p>
+                  </div>
+                  <div>
+                    <p className="text-muted-foreground">Free</p>
+                    <p className="font-medium tabular-nums">
+                      {formatBytes(stats.disk_space_usage.free_bytes)}
+                    </p>
+                  </div>
+                  <div>
+                    <p className="text-muted-foreground">Usage</p>
+                    <p className="font-medium tabular-nums">
+                      {stats.disk_space_usage.usage_percent.toFixed(2)}%
+                    </p>
+                  </div>
+                </div>
+              </CardContent>
+            </Card>
+          </>
+        ) : null}
+      </main>
+    </div>
+  );
+}

frontend/src/components/layout/Header.tsx

@@ -19,6 +19,7 @@ import {
   PanelRightOpen,
   LogOut,
   Moon,
+  Shield,
   Sun,
 } from "lucide-react";
 import { useState } from "react";
@@ -93,6 +94,13 @@ export default function Header({ sidebarOpen, onToggleSidebar, viewerOpen, onTog
               <p className="text-xs text-muted-foreground truncate">{user?.email}</p>
             </div>
             <DropdownMenuSeparator />
+            {user?.is_admin && (
+              <DropdownMenuItem className="cursor-pointer" onClick={() => router.push("/admin")}>
+                <Shield className="w-4 h-4 mr-2" />
+                Admin metrics
+              </DropdownMenuItem>
+            )}
+            {user?.is_admin && <DropdownMenuSeparator />}
             <DropdownMenuItem className="text-destructive cursor-pointer" onClick={handleLogout}>
               <LogOut className="w-4 h-4 mr-2" />
               Sign out