feat(admin): add /admin dashboard with analytics, moderation, health

Phases 0-3 per REQUIREMENTS-admin-dashboard.md:

Phase 0 - Admin Auth Foundation
- ADMIN_EMAILS env var, require_admin dep, canViewAdmin flag in /api/auth/me
- Disabled-user block on login, guest, refresh
- /admin/* layout with auth gate, sidebar (Analytics/Moderation/Health/Review feedback)
- Dashboard menu item in user nav for admins

Phase 1 - Analytics Dashboard
- GET /api/admin/analytics/{users,chats,feedback,tokens} with date range filter
- Frontend: stat cards, 5 chart families, date filter, /admin/analytics page
- Token usage block (totalTokens, promptTokens, completionTokens, tokensByModel, cost)

Phase 2 - Moderation Panel
- GET /api/admin/moderation/{users,chats} paginated, with search
- POST /disable toggle, DELETE /chats/{id} soft delete (deletedAt)
- Frontend: Users tab + Chats tab with search, pagination, actions

Phase 3 - System Health Dashboard
- GET /api/admin/health (status, db, mcp, uptimeSeconds) with MCP async-with fix
- GET /api/admin/health/metrics (8 fields incl. totalTokens24h, tokenRate24h, costEstimate24h)
- Frontend: status cards, metrics grid, 30s auto-refresh

Cross-cutting
- Rate-limit exemption for /api/admin/*
- ChatTokenUsage model + 2 alembic migrations (deletedAt + ChatTokenUsage)
- Admin canViewTokenUsage flag (admin supersedes reviewer)
- require_feedback_reviewer accepts admin OR reviewer emails
- /review/* auth-gated shell (ReviewShell) for sole reviewers
- /register + /login: bounce fix + optional 'Continue as guest' path (MSAL untouched)
- 90 backend tests + 33 frontend unit tests + 18 e2e tests
- docs/admin-api.md, CHANGELOG.md, README.md updated
- .gitignore: ignore armada/, .opencode/, .agents/, DEFECTS.md, ADVERSARIAL_REVIEW.md, screenshots/, eval artifacts

Author: rafmacalaba

.gitignore

@@ -84,3 +84,22 @@ backend/evals/personas/
 # Python
 __pycache__/
 *.pyc
+
+# Armada orchestration artifacts (not part of upstream/dev)
+armada/
+armada.yaml
+.opencode/
+.agents/
+DEFECTS.md
+ADVERSARIAL_REVIEW.md
+antigravity_chat_history.md
+screenshots/
+
+# Backend eval artifacts (not part of the PR)
+backend/eval_run_outputs.md
+backend/evals/logs/
+backend/evals/peer_reviews/
+backend/evals/reports/
+
+# SDD contract artifacts (armada)
+REQUIREMENTS-*.md

CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased] - 2026-08-02
+
+### Added
+
+- /admin dashboard at /admin/{analytics,moderation,health}
+- Backend: 4 analytics endpoints (users, chats, feedback, tokens) with date range filter
+- Backend: 4 moderation endpoints (list users, disable toggle, list chats, soft delete)
+- Backend: 2 health endpoints (status + metrics incl. token rate and cost)
+- Token usage tracking via new ChatTokenUsage model
+- ADMIN_EMAILS env var for admin allowlist
+- canViewAdmin flag in /api/auth/me
+- Disabled-user auth block on login, guest, refresh
+- Soft delete for chats via deletedAt column
+- Rate limit exemption for /api/admin/* paths
+- Dev-only auto table creation for ChatTokenUsage
+
+### Fixed
+
+- Health endpoint now returns string db/mcp state and uptimeSeconds
+- Moderation search strips null bytes; reversed date range returns 400

README.md

@@ -10,6 +10,7 @@
     <a href="#getting-started">Getting Started</a> ·
     <a href="#configuration">Configuration</a> ·
     <a href="#authentication">Authentication</a> ·
+    <a href="#admin-dashboard">Admin Dashboard</a> ·
     <a href="#deployment">Deployment</a> ·
     <a href="DEVELOPER.md">Developer Guide</a> ·
     <a href="https://worldbank.github.io/data-ai-chatbot">Documentation</a>
@@ -307,6 +308,7 @@ pnpm dev           # Start dev server (http://localhost:3001)
 | `CORS_ORIGINS`                    | No       | Comma-separated allowed origins                                     |
 | `ENVIRONMENT`                     | No       | `development` / `production`                                        |
 | `AUTH_PROVIDER`                   | No       | `guest` \| `user` \| `msal` (see [Authentication](#authentication)) |
+| `ADMIN_EMAILS`                    | No       | Comma-separated email allowlist for the admin dashboard (empty = no admin access) |
 | `RATE_LIMIT_ENABLED`              | No       | Enable per-user/IP rate limiting                                    |
 | `LOG_FILE`                        | No       | Log output file path                                                |
 
@@ -355,6 +357,41 @@ See [`frontend/docs/env-variables.md`](frontend/docs/env-variables.md) for the f
 
 ---
 
+## Admin Dashboard
+
+The application ships with an admin dashboard at `/admin` for usage analytics, content moderation, and system health. All `/admin/*` pages and `/api/admin/*` endpoints are gated by the `ADMIN_EMAILS` allowlist; non-admin users get a 403 both in the UI and at the API layer.
+
+### Enabling admin access
+
+Set `ADMIN_EMAILS` on the backend with a comma-separated list of allowed email addresses:
+
+```bash
+# backend/.env
+ADMIN_EMAILS=admin@org.com,ops@org.com
+```
+
+When `ADMIN_EMAILS` is empty, no one has admin access — every `/api/admin/*` request returns 403 and `canViewAdmin` is `false`.
+
+### Accessing the dashboard
+
+1. Log in with an account whose email is listed in `ADMIN_EMAILS`.
+2. Visit `/admin`.
+
+The admin shell checks the `canViewAdmin` flag returned by `GET /api/auth/me` and shows a 403 page to non-admins. A sidebar links to the three pages:
+
+| Page      | URL                  | What it shows                                                                                                              |
+| --------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Analytics | `/admin/analytics`   | Stat cards and charts for users, chats, feedback, and token usage; date-range filter (Last 7d / 30d / 90d)                 |
+| Moderation | `/admin/moderation` | User management (search, disable/enable) and chat browser (search by title, soft delete), with pagination                  |
+| Health    | `/admin/health`      | API / database / MCP status cards and operational metrics; auto-refreshes every 30 seconds                                 |
+
+Token usage is tracked per message via the `ChatTokenUsage` model and surfaces on **Analytics** (totals, per-model, cost estimates) and **Health** (24-hour totals and token rate).
+
+Full endpoint reference: [`docs/admin-api.md`](docs/admin-api.md).
+Feature contract: [`REQUIREMENTS-admin-dashboard.md`](REQUIREMENTS-admin-dashboard.md).
+
+---
+
 ## Deployment
 
 ### Docker Compose (development / testing)
@@ -503,6 +540,8 @@ Additional reference docs in this repository:
 - [frontend/docs/env-variables.md](frontend/docs/env-variables.md) — full frontend env var reference
 - [docs/docker-setup.md](docs/docker-setup.md) — Docker setup details
 - [docs/security-guardrails-audit.md](docs/security-guardrails-audit.md) — security audit summary
+- [docs/admin-api.md](docs/admin-api.md) — admin dashboard API reference
+- [REQUIREMENTS-admin-dashboard.md](REQUIREMENTS-admin-dashboard.md) — admin dashboard feature contract
 
 ---
 

backend/alembic/versions/9bab245e8167_add_user_disabled_column.py

@@ -0,0 +1,34 @@
+"""add_user_disabled_column
+
+Revision ID: 9bab245e8167
+Revises: k2m3n4o5p6q7
+Create Date: 2026-08-01 19:57:15.693715
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "9bab245e8167"
+down_revision: Union[str, None] = "k2m3n4o5p6q7"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column(
+        "User",
+        sa.Column("disabled", sa.Boolean(), nullable=False, server_default=sa.false()),
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column("User", "disabled")
+    # ### end Alembic commands ###

backend/alembic/versions/l3m4n5o6p7q8_add_deleted_at_to_chat.py

@@ -0,0 +1,30 @@
+"""add_deleted_at_to_chat
+
+Revision ID: l3m4n5o6p7q8
+Revises: 9bab245e8167
+Create Date: 2026-08-02 12:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "l3m4n5o6p7q8"  # pragma: allowlist secret
+down_revision: Union[str, None] = "9bab245e8167"  # pragma: allowlist secret
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "Chat",
+        sa.Column("deletedAt", sa.DateTime(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("Chat", "deletedAt")

backend/alembic/versions/m4n5o6p7q8r9_add_chattokenusage_table.py

@@ -0,0 +1,39 @@
+"""add_chattokenusage_table
+
+Revision ID: m4n5o6p7q8r9
+Revises: l3m4n5o6p7q8
+Create Date: 2026-08-02 14:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+from app.db.migration_utils import grant_table_to_app_user
+
+revision: str = "m4n5o6p7q8r9"  # pragma: allowlist secret
+down_revision: Union[str, None] = "l3m4n5o6p7q8"  # pragma: allowlist secret
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "ChatTokenUsage",
+        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("chatId", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("messageId", sa.String(length=64), nullable=False),
+        sa.Column("totalTokens", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("costUSD", sa.Float(), nullable=False, server_default="0.0"),
+        sa.Column("createdAt", sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("ix_chattokenusage_createdat", "ChatTokenUsage", ["createdAt"])
+    grant_table_to_app_user(op, "ChatTokenUsage")
+
+
+def downgrade() -> None:
+    op.drop_table("ChatTokenUsage")

backend/app/api/deps.py

@@ -33,6 +33,22 @@
 logger = logging.getLogger(__name__)
 
 
+def _raise_if_disabled(user) -> None:
+    """Raise 403 when the resolved user has been disabled by an admin."""
+    if getattr(user, "disabled", False):
+        logger.warning("Account disabled, rejecting authentication: user_id=%s", user.id)
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Account has been disabled",
+        )
+
+
+async def invalidate_user_cache(user_id: str) -> None:
+    """Drop a user's cached auth entry so the next request re-reads from the DB."""
+    async with _user_cache_lock:
+        _user_cache.pop(user_id, None)
+
+
 async def get_current_user(
     request: Request,
     credentials: Optional[HTTPAuthorizationCredentials] = Depends(security),
@@ -103,6 +119,7 @@ async def get_current_user(
                     user = await get_or_create_user_from_azure_claims(
                         db, azure_oid=oid, email=email, name=name
                     )
+                    _raise_if_disabled(user)
                     user_dict = {"id": str(user.id), "type": user.type or "regular"}
                     async with _user_cache_lock:
                         _user_cache[msal_cache_key] = (time.monotonic(), user_dict)
@@ -154,6 +171,7 @@ async def get_current_user(
                     )
                     payload = None
                 else:
+                    _raise_if_disabled(user)
                     # Check if password was changed after token was issued (session invalidation)
                     if jti and hasattr(user, "password_changed_at") and user.password_changed_at:
                         token_issued_at = payload.get("iat")
@@ -210,6 +228,7 @@ async def get_current_user(
             try:
                 user_id = UUID(validated_user_id)
                 user = await get_user_by_id(db, user_id)
+                _raise_if_disabled(user)
                 logger.debug(
                     "Guest user lookup: user_id=%s, found=%s, email=%s",
                     user_id,
@@ -285,6 +304,7 @@ async def get_current_user(
             try:
                 user_id = UUID(validated_user_id)
                 user = await get_user_by_id(db, user_id)
+                _raise_if_disabled(user)
                 logger.info(
                     "Regular user lookup: user_id=%s, found=%s, email=%s",
                     user_id,
@@ -338,6 +358,7 @@ async def get_current_user(
                             return {**cached, "_restore_user": True}
 
                 user = await get_user_by_id(db, user_id)
+                _raise_if_disabled(user)
                 logger.debug(
                     "Regular user lookup (raw UUID fallback): user_id=%s, found=%s, email=%s",
                     user_id,
@@ -406,7 +427,9 @@ def get_reviewer_emails() -> set[str]:
     Parse FEEDBACK_REVIEWER_EMAILS into a lower-cased set of email addresses.
 
     Centralised here so that both require_feedback_reviewer (access control) and
-    /api/auth/me (canViewTokenUsage flag) use identical parsing logic.
+    /api/auth/me (canViewTokenUsage flag) use identical parsing logic.  Admins
+    (in ADMIN_EMAILS) are implicitly allowed too — see require_feedback_reviewer
+    for the union logic.
     """
     raw = getattr(settings, "FEEDBACK_REVIEWER_EMAILS", "") or ""
     return {e.strip().lower() for e in raw.split(",") if e.strip()}
@@ -417,12 +440,17 @@ async def require_feedback_reviewer(
     db: AsyncSession = Depends(get_db),
 ) -> dict:
     """
-    Require authenticated user whose email is in FEEDBACK_REVIEWER_EMAILS.
+    Require authenticated user whose email is in FEEDBACK_REVIEWER_EMAILS
+    or ADMIN_EMAILS (admin supersedes reviewer).
+
     Use for feedback review/list endpoints. Raises 403 if not allowed.
     """
-    allowed = get_reviewer_emails()
-    if not allowed:
-        logger.warning("require_feedback_reviewer: FEEDBACK_REVIEWER_EMAILS is empty")
+    reviewer_emails = get_reviewer_emails()
+    admin_emails = get_admin_emails()
+    if not reviewer_emails and not admin_emails:
+        logger.warning(
+            "require_feedback_reviewer: both FEEDBACK_REVIEWER_EMAILS and ADMIN_EMAILS are empty"
+        )
         raise HTTPException(
             status_code=status.HTTP_403_FORBIDDEN,
             detail="Feedback review is not configured or access is disabled",
@@ -449,7 +477,8 @@ async def require_feedback_reviewer(
             status_code=status.HTTP_403_FORBIDDEN,
             detail="You do not have permission to view feedback",
         )
-    if user.email.strip().lower() not in allowed:
+    email_lower = user.email.strip().lower()
+    if email_lower not in reviewer_emails and email_lower not in admin_emails:
         logger.info(
             "require_feedback_reviewer: email not in allowlist, user_id=%s",
             user_id_str,
@@ -459,3 +488,50 @@ async def require_feedback_reviewer(
             detail="You do not have permission to view feedback",
         )
     return current_user
+
+
+def get_admin_emails() -> set[str]:
+    """Parse ADMIN_EMAILS into a lower-cased set of email addresses."""
+    raw = getattr(settings, "ADMIN_EMAILS", "") or ""
+    return {e.strip().lower() for e in raw.split(",") if e.strip()}
+
+
+async def require_admin(
+    current_user: dict = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> dict:
+    """
+    Require authenticated user whose email is in ADMIN_EMAILS.
+    Use for admin dashboard endpoints. Raises 403 if not allowed.
+    """
+    allowed = get_admin_emails()
+    if not allowed:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admin access is not configured",
+        )
+    user_id_str = current_user.get("id")
+    if not user_id_str:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User ID not found",
+        )
+    try:
+        user_uuid = UUID(user_id_str)
+    except (ValueError, TypeError):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Invalid user ID",
+        )
+    user = await get_user_by_id(db, user_uuid)
+    if not user or not getattr(user, "email", None):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You do not have admin access",
+        )
+    if user.email.strip().lower() not in allowed:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You do not have admin access",
+        )
+    return current_user

backend/app/api/v1/admin/__init__.py

@@ -0,0 +1 @@
+"""Admin dashboard API routes."""