# Admin Dashboard

> **URL**: `/jim19ud83/playground/dashboard`  
> **Access**: `ROLE_ADMIN` required  
> **Status**: ✅ Live in production

---

## Overview

The Admin Dashboard is a comprehensive monitoring and management interface for Shamra Academia. It provides real-time insights into platform usage, user engagement, AI costs, and system health.

---

## Tab Structure

The dashboard uses a tabbed interface with **18 sections**, organized into logical groups:

### 📊 Analytics
| Tab | Description |
|-----|-------------|
| **Overview** | Daily/monthly AI usage, costs, budget tracking, trend charts |
| **Usage Details** | Per-operation and per-model breakdown |
| **Engagement** | User engagement metrics |
| **Search CTR** | Search click-through rates, zero-result queries, position distribution |

### 👥 Users & Subscriptions
| Tab | Description |
|-----|-------------|
| **Top Users** | Highest AI credit consumers |
| **Trial Users** | Users on trial tier |
| **All Users** | Full user list with stats, registration trends, profile completion analytics |
| **Pricing & Tiers** | Playground subscription tier configuration |

### 🤖 AI Services
| Tab | Description |
|-----|-------------|
| **OCR** | OCR job statistics, success/failure rates, page counts |
| **AI Detection** | AI content detection usage stats |

### 📧 Communications
| Tab | Description |
|-----|-------------|
| **Welcome Email** | Email template editor for welcome emails |
| **Welcome Chat** | Welcome chat message configuration |
| **Notifications** | Push notification statistics, delivery rates |
| **Follow Emails** | Follow notification email stats |
| **CSAT** | Customer satisfaction feedback analysis |

### ⚙️ System
| Tab | Description |
|-----|-------------|
| **Settings** | System configuration toggles |
| **Errors** | Recent error log viewer |

### External Links
- **📧 Newsletter Dashboard** → `/jim19ud83/newsletter`
- **📝 Blog** → `/jim19ud83/blog`

---

## Key Features

### Budget Monitoring
- Real-time monthly/daily AI spend tracking
- Budget limit warnings
- Cost breakdown by model (GPT-4, Claude, etc.)

### User Statistics
- Registration trends (12-month chart)
- Login activity (30-day chart)
- Country/locale/degree distribution
- Verification rates
- Newsletter subscription rates

### Profile Completion Analytics
Added March 2026 — tracks user profile completeness:

| Tier | Score Range | Icon |
|------|-------------|------|
| Beginner | 0-25% | 👶 |
| Developing | 26-50% | 🌱 |
| Researcher | 51-75% | 📖 |
| Scholar | 76-99% | 📚 |
| Scientist | 100% | 🎓 |

Features:
- Distribution cards showing users per tier
- Visual progress bar
- Field completion rates (photo, bio, interests, etc.)
- Paginated list of users with >50% completion
- Clickable profile links

### Search CTR Analytics
Tracks search quality:
- Total searches, clicks, CTR percentage
- Queries without clicks (potential UX issues)
- Zero-result queries (indexing gaps)
- Click position distribution
- Daily trend charts

### OCR Statistics
- Jobs by status (pending, processing, completed, failed)
- Page counts and credit usage
- Success/failure rates
- Recent job list

---

## API Endpoints

All endpoints require `ROLE_ADMIN`:

| Endpoint | Purpose |
|----------|---------|
| `GET /api/user-stats` | User statistics and trends |
| `GET /api/ocr-stats` | OCR job statistics |
| `GET /api/search-ctr-stats` | Search CTR metrics |
| `GET /api/search-ctr-trend` | Daily search/click trend |
| `GET /api/search-ctr-top-queries` | Top search queries |
| `GET /api/search-ctr-no-clicks` | Queries without clicks |
| `GET /api/search-ctr-zero-results` | Zero-result queries |
| `GET /api/search-ctr-positions` | Click position distribution |
| `GET /api/notification-stats` | Notification delivery stats |
| `GET /api/csat-stats` | CSAT feedback stats |
| `GET /api/profile-completion` | Profile completion distribution |
| `POST /api/toggle-setting` | Toggle system settings |
| `POST /api/save-welcome-email` | Save welcome email template |
| `POST /api/save-welcome-chat` | Save welcome chat config |

---

## Mobile UX

The dashboard includes mobile-friendly features:
- **Dropdown selector** on mobile (replaces horizontal tabs)
- **Scrollable tabs** on tablet
- **Responsive grids** for stat cards
- **Touch-friendly** buttons and pagination

---

## Files

| File | Purpose |
|------|---------|
| `src/Controller/PlaygroundAdminController.php` | All routes and API endpoints |
| `templates/admin/playground/dashboard.html.twig` | Template (~5000 lines) |

---

## Future Enhancements

### 🔴 Priority 1 — Quick Wins

| Feature | Description | Effort |
|---------|-------------|--------|
| **Budget Alerts** | Warning banner at 80%, email at 90%, auto-pause at 100% | 2h |
| **User Search** | Quick search by email/username with autocomplete | 3h |
| **Export to CSV** | Download user lists, search queries, OCR jobs | 4h |
| **Error Badges** | Show error count on Errors tab, toast on new CRITICAL | 2h |

### 📊 Priority 2 — Analytics Enhancements

| Feature | Description | Effort |
|---------|-------------|--------|
| **Date Range Picker** | Custom date range for all charts (not just 7d/30d/90d) | 4h |
| **Comparison Mode** | "vs previous period" with +/-% change indicators | 6h |
| **Cohort Analysis** | Users by registration month, retention curves | 8h |
| **Scheduled Reports** | Weekly email digest with key metrics | 4h |

### 👥 Priority 3 — User Management

| Feature | Description | Effort |
|---------|-------------|--------|
| **User Detail Modal** | Click username → slide-out with full profile, activity, quick actions | 6h |
| **Bulk Actions** | Send email, grant/revoke credits, export selected users | 8h |
| **Impersonate User** | "Login as user" for debugging (audit logged) | 4h |

### 🔍 Priority 4 — Search Quality

| Feature | Description | Effort |
|---------|-------------|--------|
| **Search Suggestions Editor** | Manually curate suggested searches | 4h |
| **Synonym Management** | Map terms (e.g., "AI" = "artificial intelligence") | 6h |
| **A/B Test Dashboard** | Compare search algorithm variants | 12h |
| **Result Boosting** | Manually boost specific results for queries | 4h |

### ⚡ Priority 5 — Performance

| Feature | Description | Effort |
|---------|-------------|--------|
| **Redis Caching** | Cache stats with 5-min TTL, manual refresh button | 3h |
| **Lazy Load Charts** | Load heavy visualizations only when tab is visible | 2h |
| **API Response Compression** | Gzip large JSON responses | 1h |

### 🎨 Priority 6 — UX Polish

| Feature | Description | Effort |
|---------|-------------|--------|
| **Dark Mode** | Toggle for night use, reduce eye strain | 4h |
| **Keyboard Shortcuts** | `1-9` tabs, `/` search, `R` refresh | 3h |
| **Remember Last Tab** | Persist last active tab in localStorage | 1h |
| **Pinned Tabs** | Pin frequently used tabs to front | 2h |

### 🔐 Priority 7 — Audit & Security

| Feature | Description | Effort |
|---------|-------------|--------|
| **Admin Action Log** | Track who changed settings, sent emails, IP logging | 6h |
| **Role-based Tabs** | Support staff → Users only, Finance → Budget only | 4h |
| **Two-Factor for Admin** | Require 2FA for admin dashboard access | 4h |

---

## Implementation Roadmap

### Phase 1 (Week 1) — Essential
- [ ] Budget alerts (80%/90%/100%)
- [ ] User search box
- [ ] Export to CSV
- [ ] Error count badge

### Phase 2 (Week 2-3) — Analytics
- [ ] Date range picker
- [ ] Comparison mode
- [ ] Redis caching

### Phase 3 (Month 2) — User Management
- [ ] User detail modal
- [ ] Bulk actions
- [ ] Admin action log

### Phase 4 (Month 3) — Search & Polish
- [ ] Search suggestions editor
- [ ] Dark mode
- [ ] Keyboard shortcuts