feat: add detailed Discord analytics to admin dashboard

[mchestr]

Summary

• Add 6 new analytics sections to the Discord admin dashboard that expose previously hidden bot integrations
• Help Command Stats: tracks which commands users ask help about most
• Account Linking Metrics: shows link requests over time and repeat requesters
• Media Marking Breakdown: individual command usage (!finished, !keep, !notinterested, etc.) with top media marked
• Context Metrics: context clear patterns by command and frequent clearers
• Error Analysis: error categorization by type/command with sample error messages
• Selection Stats: selection menu distribution (1-5) with success rate

Test plan

• Navigate to /admin/discord and verify new "Detailed Analytics" section appears
• Verify each chart/table displays correctly with empty state messages when no data
• Verify date filter affects the new analytics sections
• Check responsive layout on mobile/tablet viewports

🤖 Generated with Claude Code

[claude]

Claude finished @mchestr's task in 2m 10s —— View job

---

PR Review: Discord Detailed Analytics

Tasks

• Read all changed files to understand implementation
• Analyze code against CLAUDE.md guidelines
• Check for code quality, bugs, performance, security issues
• Verify test coverage
• Post comprehensive review via gh pr comment

---

Review Complete ✅

I've posted a comprehensive code review analyzing this PR against the project's CLAUDE.md guidelines. The review covers:

• ✅ Strengths: Excellent architecture patterns, security practices, and code organization
• ⚠️ Critical Issues:
  • Missing test coverage (blocker)
  • File size violation in lib/discord/audit.ts (862 lines vs 150 line limit)
  • N+1 query performance issue in getCommandStats()
• 🔧 Medium Priority: Performance optimizations, JSDoc documentation
• 🐛 Low Priority: Type safety improvements, minor code quality issues

Overall Assessment: Well-structured implementation that follows project conventions, but requires addressing critical blockers before merge (tests, file organization, query optimization).

View detailed review comment

---

[claude]

Code Review: Discord Analytics Dashboard

Overview

This PR adds 6 new detailed analytics sections to the Discord admin dashboard, exposing previously hidden bot integration metrics. The implementation is well-structured and follows the project's conventions closely.

---

✅ Strengths

1. Excellent adherence to project conventions:

   • Server Actions pattern correctly used with 'use server' directive
   • Proper admin authorization checks with requireAdmin()
   • Components use 'use client' only when necessary (for Chart.js interactivity)
   • Follows Server Component by default approach (page.tsx is a Server Component)

2. Security best practices followed:

   • All server actions have proper auth checks at actions/discord-activity.ts:39, 82, 101, etc.
   • No SQL injection risks (using Prisma exclusively)
   • Error handling returns safe error objects without exposing internals
   • Input validation with date conversions and sanitization

3. Good error handling:

   • Graceful fallbacks with empty state messages
   • Proper try-catch blocks in all server actions
   • Null-safe component rendering

4. Data serialization:

   • Dates properly converted to ISO strings for client consumption (actions/discord-activity.ts:59-62)

5. Code organization:

   • Clear separation of concerns (actions, components, lib)
   • Consistent naming conventions
   • Good use of TypeScript interfaces

6. Testing: All components include data-testid attributes following Playwright best practices

---

⚠️ Issues & Recommendations

1. File Size Violations (High Priority)

Per CLAUDE.md guidelines (line 197-199), React components should be max 200-300 lines. Several files exceed this:

• discord-media-marking-breakdown.tsx: 230 lines (acceptable but near limit)
• lib/discord/audit.ts: 857 lines ❌ (Significantly exceeds 150-line utility module limit)

Recommendation: Split lib/discord/audit.ts into separate modules:

lib/discord/audit/
  ├── core.ts          (create, update, get logs)
  ├── stats.ts         (command stats, daily activity)
  ├── help-stats.ts    (help command analytics)
  ├── linking.ts       (account linking metrics)
  ├── media.ts         (media marking breakdown)
  ├── context.ts       (context metrics)
  ├── errors.ts        (error analysis)
  ├── selection.ts     (selection menu stats)
  └── index.ts         (re-exports)

2. Missing JSDoc Documentation (Medium Priority)

Complex analytics functions lack documentation (per CLAUDE.md lines 291-362):

• lib/discord/audit.ts: Functions like getMediaMarkingBreakdown, getErrorAnalysis, getSelectionMenuStats have non-obvious logic
• Should include JSDoc with:
  • Algorithm explanations for complex aggregations
  • Date range handling behavior
  • Return value structures

Example:

/**
 * Get media marking breakdown by command type.
 *
 * ## Algorithm
 * 1. Groups all MEDIA_MARK commands by commandName
 * 2. Calculates success/failure rates per command
 * 3. Extracts top 10 media titles from successful marks
 *
 * @param startDate - Start of date range (inclusive)
 * @param endDate - End of date range (exclusive)
 * @returns Breakdown with command stats and top marked media
 */

3. Missing Test Coverage (High Priority)

No test files included in PR. Per CLAUDE.md (lines 246-289):

Required tests:

• Component tests for all 6 new components in components/admin/discord/__tests__/
• Server action tests for new analytics functions
• Mock Chart.js and test empty states, loading states, error states

Example test structure:

// components/admin/discord/__tests__/discord-help-stats.test.tsx
describe('DiscordHelpStats', () => {
  it('should display empty state when no data', () => {
    render(<DiscordHelpStats data={null} />)
    expect(screen.getByText('No help command data available')).toBeInTheDocument()
  })

  it('should display stats when data provided', () => {
    const mockData = { totalHelpRequests: 10, ... }
    render(<DiscordHelpStats data={mockData} />)
    expect(screen.getByTestId('discord-help-stats')).toBeInTheDocument()
  })
})

4. Performance Considerations (Medium Priority)

a) N+1 Query Pattern in getCommandStats (lib/discord/audit.ts:226-256):

const statsPromises = logs.map(async (log) => {
  const [successCount, failedCount] = await Promise.all([
    prisma.discordCommandLog.count({ ... }),  // N queries
    prisma.discordCommandLog.count({ ... }),  // N queries
  ])
})

Issue: If there are 20 different commands, this executes 40 additional database queries.

Better approach:

// Single query approach
const statusGroups = await prisma.discordCommandLog.groupBy({
  by: ['commandName', 'commandType', 'status'],
  where: { createdAt: { gte: startDate, lt: endDate } },
  _count: { _all: true }
})

// Process in memory
const stats = new Map()
for (const group of statusGroups) {
  const key = `${group.commandName}-${group.commandType}`
  if (!stats.has(key)) {
    stats.set(key, { commandName: group.commandName, successCount: 0, failedCount: 0 })
  }
  if (group.status === 'SUCCESS') stats.get(key).successCount = group._count._all
  if (group.status === 'FAILED') stats.get(key).failedCount = group._count._all
}

b) Page Component Fetches Too Much Data (app/admin/discord/page.tsx:38-42):

Three parallel Promise.all fetches is good, but loading all detailed stats on page load may be slow:

const [dashboardResult, logsResult, detailedResult] = await Promise.all([
  getDiscordDashboardData({ startDate, endDate }),
  getDiscordActivityLogs({ limit: 20 }),
  getDiscordDetailedStats({ startDate, endDate }),  // 6 separate analytics queries
])

Recommendation: Consider lazy loading detailed analytics sections:

• Initial render shows summary cards + charts
• Detailed sections load on scroll/user interaction (use Suspense boundaries)

5. Type Safety (Low Priority)

a) Magic strings for command types (lib/discord/audit.ts):

commandType: "HELP" as DiscordCommandType  // Lines 441, 502, 570, 669, 726, 811

Better: Import enum values from Prisma:

import { DiscordCommandType } from '@/lib/generated/prisma/client'

const where = {
  commandType: DiscordCommandType.HELP,
  // ...
}

b) Component props lack descriptions in interfaces. Add JSDoc to clarify expected data structures.

6. Minor Code Quality Issues

a) Inconsistent null handling (app/admin/discord/page.tsx:86):

<DiscordBotStatus status={dashboard?.botStatus ?? null} />

This is fine, but dashboard?.botStatus already returns undefined if dashboard is null, so ?? null is redundant.

b) Hardcoded slice limits:

• topTopics = data.helpByTopic.slice(0, 8) (discord-help-stats.tsx:36)
• data.repeatRequestUsers.slice(0, 5) (discord-linking-metrics.tsx:136)
• data.topClearUsers.slice(0, 5) (discord-context-metrics.tsx:99)

Consider extracting to constants:

const MAX_TOP_TOPICS = 8
const MAX_REPEAT_USERS = 5

c) Error type guards missing:

} catch (error) {
  logger.error("Failed to get help stats", error instanceof Error ? error : undefined)
  // Could use unknown type + proper type guard
}

---

🧪 Testing Checklist (Missing)

Based on CLAUDE.md requirements, this PR should include:

• Unit tests for all 6 new components
• Tests for server actions with mocked Prisma
• Tests for empty states, error states, loading states
• Tests for date filtering behavior
• E2E test for admin dashboard navigation (optional but recommended)

---

🔒 Security Assessment

✅ No security vulnerabilities detected:

• Proper authorization checks on all endpoints
• Prisma parameterized queries (no SQL injection risk)
• No XSS vectors (React auto-escapes, no dangerouslySetInnerHTML)
• Error messages don't leak sensitive info
• Date inputs properly validated and sanitized

---

📊 Performance Impact

Database Queries per Page Load:

• Dashboard summary: ~6 queries (via getSummaryStats)
• Daily activity: 1 query
• Command stats: N+1 pattern (20-50 queries depending on command variety)
• Active users: 1 query
• Bot status: 3 queries
• Recent logs: 2 queries
• Detailed stats: ~12-18 additional queries

Total: Approximately 30-50 database queries on initial page load.

Recommendation: Add caching with revalidatePath or consider Redis for analytics data that doesn't need real-time updates.

---

📝 Summary

Overall Assessment: ✅ Approve with recommendations

This is solid work that follows project conventions well. The main concerns are:

1. Critical: Missing test coverage
2. High: File size violations (audit.ts needs splitting)
3. Medium: N+1 query performance issue in getCommandStats
4. Low: Missing JSDoc documentation for complex functions

The code is functional, secure, and well-structured. Address the test coverage and file organization issues before merging.

---

Suggested Action Items

1. Add comprehensive test coverage (unit tests minimum)
2. Split lib/discord/audit.ts into smaller, focused modules
3. Optimize getCommandStats to eliminate N+1 queries
4. Add JSDoc to complex analytics functions
5. Consider lazy loading detailed analytics sections for better initial page load performance

Great work overall! The analytics will provide valuable insights into Discord bot usage. 🎉

[claude]

Code Review: Discord Detailed Analytics

📊 Overview

This PR adds 6 new detailed analytics sections to the Discord admin dashboard. The implementation is well-structured and follows most project conventions, but there are several important areas for improvement.

---

✅ Strengths

1. Excellent adherence to architecture patterns:

   • Server Actions correctly used with proper 'use server' directive
   • All actions have admin authorization checks via requireAdmin()
   • Components use 'use client' only when necessary (Chart.js interactivity)
   • Server Component by default approach (page.tsx fetches data server-side)
   • Proper date serialization for client consumption (actions/discord-activity.ts:59-62)

2. Security best practices:

   • All server actions have proper auth checks
   • No SQL injection risks (Prisma exclusively)
   • Error handling returns safe error objects
   • Input validation with date conversions

3. Good code organization:

   • Clear separation of concerns (actions, components, lib)
   • Consistent naming conventions
   • Proper use of TypeScript interfaces

4. Accessibility: All components include data-testid attributes following Playwright best practices

---

⚠️ Critical Issues

1. CRITICAL: Missing Test Coverage (BLOCKER)

No test files included in this PR. Per CLAUDE.md lines 246-289, comprehensive test coverage is required.

Required tests:

• Component tests for all 6 new components in components/admin/discord/__tests__/
• Server action tests for new analytics functions
• Mock Chart.js and test empty states, loading states, error states

Example structure needed:

// components/admin/discord/__tests__/discord-help-stats.test.tsx
describe('DiscordHelpStats', () => {
  it('should display empty state when no data', () => {
    render(<DiscordHelpStats data={null} />)
    expect(screen.getByText('No help command data available')).toBeInTheDocument()
  })

  it('should display stats when data provided', () => {
    const mockData = { totalHelpRequests: 10, helpByTopic: [], ... }
    render(<DiscordHelpStats data={mockData} />)
    expect(screen.getByTestId('discord-help-stats')).toBeInTheDocument()
  })
})

Recommendation: Add comprehensive test coverage before merging.

---

2. HIGH: File Size Violation (lib/discord/audit.ts: 862 lines)

Per CLAUDE.md lines 197-199, utility modules should be max ~150 lines. This file is 5.7x over the limit.

Recommendation: Split into separate modules:

lib/discord/audit/
  ├── core.ts          (create, update, get logs - ~100 lines)
  ├── stats.ts         (command stats, daily activity - ~100 lines)
  ├── help-stats.ts    (help command analytics - ~50 lines)
  ├── linking.ts       (account linking metrics - ~60 lines)
  ├── media.ts         (media marking breakdown - ~90 lines)
  ├── context.ts       (context metrics - ~50 lines)
  ├── errors.ts        (error analysis - ~80 lines)
  ├── selection.ts     (selection menu stats - ~60 lines)
  └── index.ts         (re-exports)

This would improve maintainability, testability, and code navigation.

---

3. HIGH: N+1 Query Performance Issue (lib/discord/audit.ts:226-256)

In getCommandStats(), the code executes 2N additional database queries:

const statsPromises = logs.map(async (log) => {
  const [successCount, failedCount] = await Promise.all([
    prisma.discordCommandLog.count({ ... }),  // N queries
    prisma.discordCommandLog.count({ ... }),  // N queries
  ])
})

Impact: If there are 20 different commands, this executes 40 additional database queries.

Better approach - Use single query with groupBy:

const statusGroups = await prisma.discordCommandLog.groupBy({
  by: ['commandName', 'commandType', 'status'],
  where: { createdAt: { gte: startDate, lt: endDate } },
  _count: { _all: true }
})

// Process in memory
const stats = new Map()
for (const group of statusGroups) {
  const key = `${group.commandName}-${group.commandType}`
  if (!stats.has(key)) {
    stats.set(key, { commandName: group.commandName, successCount: 0, failedCount: 0 })
  }
  if (group.status === 'SUCCESS') stats.get(key).successCount = group._count._all
  if (group.status === 'FAILED') stats.get(key).failedCount = group._count._all
}

This reduces queries from 2N+1 to just 1.

---

🔧 Medium Priority Issues

4. Performance: Page Load Query Count (app/admin/discord/page.tsx:38-42)

The page executes approximately 30-50 database queries on initial load:

• Dashboard summary: ~6 queries
• Daily activity: 1 query
• Command stats: 20-50 queries (due to N+1 issue above)
• Active users: 1 query
• Bot status: 3 queries
• Recent logs: 2 queries
• Detailed stats: ~12-18 additional queries

Recommendations:

1. Fix the N+1 query issue (chore(deps): bump actions/checkout from 4 to 5 #3) to significantly reduce query count
2. Consider lazy loading detailed analytics sections (load on scroll/user interaction using Suspense boundaries)
3. Consider caching with revalidatePath or Redis for analytics data that doesn't need real-time updates

---

5. Missing JSDoc Documentation

Per CLAUDE.md lines 291-362, complex analytics functions should have JSDoc documentation with:

• Algorithm explanations for complex aggregations
• Date range handling behavior
• Return value structures

Functions needing documentation:

• getMediaMarkingBreakdown (lib/discord/audit.ts:565-649)
• getErrorAnalysis (lib/discord/audit.ts:724-798)
• getSelectionMenuStats (lib/discord/audit.ts:811-860)

Example:

/**
 * Get media marking breakdown by command type.
 *
 * ## Algorithm
 * 1. Groups all MEDIA_MARK commands by commandName
 * 2. Calculates success/failure rates per command
 * 3. Extracts top 10 media titles from successful marks
 *
 * @param startDate - Start of date range (inclusive)
 * @param endDate - End of date range (exclusive)
 * @returns Breakdown with command stats and top marked media
 */

---

🐛 Low Priority Issues

6. Type Safety Improvements

a) Magic strings for command types (lib/discord/audit.ts):

commandType: "HELP" as DiscordCommandType  // Lines 441, 502, 570, 669, 726, 811

Better: Import enum values from Prisma:

import { DiscordCommandType } from '@/lib/generated/prisma/client'

const where = {
  commandType: DiscordCommandType.HELP,
  // ...
}

b) Hardcoded slice limits:

• topTopics = data.helpByTopic.slice(0, 8) (discord-help-stats.tsx:36)
• data.repeatRequestUsers.slice(0, 5) (discord-linking-metrics.tsx:136)
• data.topClearUsers.slice(0, 5) (discord-context-metrics.tsx:99)

Recommendation: Extract to constants:

const MAX_TOP_TOPICS = 8
const MAX_REPEAT_USERS = 5

7. Minor Code Quality

a) Redundant null coalescing (app/admin/discord/page.tsx:86):

<DiscordBotStatus status={dashboard?.botStatus ?? null} />

The ?? null is redundant since dashboard?.botStatus already returns undefined if dashboard is null.

b) Component props lack JSDoc descriptions - Consider adding JSDoc to interfaces to clarify expected data structures.

---

🔒 Security Assessment

✅ No security vulnerabilities detected:

• Proper authorization checks on all endpoints
• Prisma parameterized queries (no SQL injection risk)
• No XSS vectors (React auto-escapes, no dangerouslySetInnerHTML)
• Error messages don't leak sensitive info
• Date inputs properly validated and sanitized

---

📝 Summary

Overall Assessment: ⚠️ Approve with required changes

This is well-structured code that follows project conventions, but has critical blockers that must be addressed:

Blockers (must fix before merge):

1. ❌ Missing test coverage - Add comprehensive unit tests
2. ❌ File size violation - Split audit.ts into smaller modules
3. ❌ N+1 query performance - Optimize getCommandStats()

Recommended improvements:
4. Add JSDoc to complex functions
5. Consider lazy loading detailed sections
6. Use Prisma enums instead of magic strings
7. Extract hardcoded limits to constants

The analytics features will provide excellent insights into Discord bot usage. Great work on the implementation structure! Just needs the critical issues addressed before merging.

---

🎯 Action Items

Before merge:

• Add comprehensive test coverage (unit tests minimum)
• Split lib/discord/audit.ts into smaller, focused modules
• Optimize getCommandStats to eliminate N+1 queries

Post-merge considerations:

• Add JSDoc to complex analytics functions
• Consider lazy loading detailed analytics sections
• Add caching strategy for analytics data