# Admin Dashboard Design Spec

## Overview

Add an admin web dashboard to the existing Agent Fox SPA, accessible at `/admin/*` routes. Provides real-time platform statistics, user management, project management, and MCP call log viewing.

## Database Changes

### User model additions
- `role`: enum `Role` (`USER` | `ADMIN`), default `USER`
- `disabled`: Boolean, default `false`

### New model: McpCallLog
| Field | Type | Description |
|-------|------|-------------|
| id | String (UUID) | Primary key |
| projectId | String (FK) | Reference to Project |
| toolName | String | MCP tool name called |
| calledAt | DateTime | Timestamp |
| durationMs | Int | Response time in ms |
| success | Boolean | Whether call succeeded |
| requestParams | Json | Request parameters |
| responseSize | Int | Response size in bytes |
| clientIp | String | Caller IP address |
| estimatedTokens | Int? | Estimated token consumption |

Indexes: `projectId`, `calledAt`, `toolName`

## Backend API

### New middleware
- `requireAdmin`: verifies `role === 'ADMIN'` from JWT payload. Returns 403 if not admin.
- Login check: `disabled === true` users get 403 on login.

### New routes (`/api/admin/`)
| Method | Path | Description |
|--------|------|-------------|
| GET | /stats | Aggregate stats (user count, project count, call count, today's active) |
| GET | /stats/trends | Time-series data (7d/30d call trends) |
| GET | /users | Paginated user list with search/sort |
| GET | /users/:id | User detail + their projects |
| PATCH | /users/:id/disable | Toggle user disabled status |
| GET | /projects | Global paginated project list |
| GET | /projects/:id | Project detail |
| DELETE | /projects/:id | Delete project |
| GET | /call-logs | Paginated call logs with filters |

### MCP call logging
In `packages/mcp`, wrap each tool handler to record a `McpCallLog` entry with timing, params, success/failure, response size, client IP, and token estimate.

## Frontend

### Routes
```
/admin              → Dashboard (stats overview)
/admin/users        → User management list
/admin/users/:id    → User detail
/admin/projects     → Project management list
/admin/projects/:id → Project detail
/admin/logs         → Call log viewer
```

### AdminLayout
- Left sidebar (200px): nav links for Dashboard / Users / Projects / Logs
- Top header: reuse theme toggle + user menu from existing Layout
- Route guard: redirect non-admin users to `/dashboard`
- Separate from existing `Layout.tsx`, parallel structure

### Dashboard page
| Card | Content |
|------|---------|
| Registered Users | Total + today's new |
| Projects | Total + today's new |
| MCP Calls | Total + today's calls |
| Active Users (7d) | Users with activity in past 7 days |
| Avg Response Time | Mean durationMs of MCP calls |
| Success Rate | Percentage of successful calls |

Below cards: 7-day call trend chart + recent calls table.

### User Management
- Table: name, email, role, projects count, created date, status (active/disabled)
- Search by name/email
- Actions: view detail, toggle disable
- Detail page: user info + list of their projects

### Project Management
- Table: name, owner, endpoints count, modules count, created date
- Search by name
- Actions: view detail, delete (with confirmation)
- Detail page: project info, modules, endpoints summary

### Call Logs
- Table: time, project name, tool name, duration, success, client IP
- Filters: project, tool name, date range, success/failure
- Pagination

## Auth Flow
- JWT payload adds `role` field
- Frontend stores role in auth context
- Admin nav entry only visible to admin users
- Non-admin accessing `/admin/*` → redirect to `/dashboard`

## Tech Stack (frontend)
- Same React 19 + React Router 7 + Tailwind CSS v4
- Reuse existing custom components (Badge, Modal, ConfirmDialog, etc.)
- Charts: lightweight solution (CSS-based or small chart lib)
- No new component library