implement initial backend structure with authentication, user management, and database integration

backend/app/routers/admin.py

@@ -0,0 +1,62 @@
+"""Admin router: operational endpoints for application management."""
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends
+
+from backend.app.db import get_conn, get_write_lock
+from backend.app.dependencies import require_admin
+
+router = APIRouter(prefix="/admin", tags=["admin"])
+
+
+@router.get("/stats")
+async def get_stats(_: dict = Depends(require_admin)) -> dict:
+    """Return aggregate statistics: user counts and token counts."""
+    conn = get_conn()
+    total_users = conn.execute("SELECT COUNT(*) FROM users").fetchone()[0]
+    users_by_role = conn.execute(
+        "SELECT role, COUNT(*) FROM users GROUP BY role ORDER BY role"
+    ).fetchall()
+    total_tokens = conn.execute(
+        "SELECT COUNT(*) FROM refresh_tokens").fetchone()[0]
+    active_tokens = conn.execute(
+        "SELECT COUNT(*) FROM refresh_tokens WHERE revoked = false AND expires_at > ?",
+        [datetime.now(timezone.utc)],
+    ).fetchone()[0]
+    return {
+        "users": {
+            "total": total_users,
+            "by_role": {row[0]: row[1] for row in users_by_role},
+        },
+        "refresh_tokens": {
+            "total": total_tokens,
+            "active": active_tokens,
+            "revoked_or_expired": total_tokens - active_tokens,
+        },
+    }
+
+
+@router.get("/health/db")
+async def db_health(_: dict = Depends(require_admin)) -> dict:
+    """Verify DuckDB is reachable."""
+    conn = get_conn()
+    result = conn.execute("SELECT 1").fetchone()[0]
+    return {"status": "ok" if result == 1 else "error"}
+
+
+@router.post("/tokens/purge", status_code=200)
+async def purge_tokens(_: dict = Depends(require_admin)) -> dict:
+    """Delete all expired or revoked refresh tokens. Returns count removed."""
+    conn = get_conn()
+    lock = get_write_lock()
+    now = datetime.now(timezone.utc)
+    async with lock:
+        before = conn.execute(
+            "SELECT COUNT(*) FROM refresh_tokens").fetchone()[0]
+        conn.execute(
+            "DELETE FROM refresh_tokens WHERE revoked = true OR expires_at <= ?", [
+                now]
+        )
+        after = conn.execute(
+            "SELECT COUNT(*) FROM refresh_tokens").fetchone()[0]
+    return {"deleted": before - after, "remaining": after}