Skip to Content
📚 MyStoryFlow Docs — Your guide to preserving family stories

Admin Dashboard System

The MyStoryFlow Admin Dashboard is a comprehensive administrative interface built with Next.js that provides monitoring, management, and control over platform operations, user administration, AI features, content oversight, and system health.

🏗️ Architecture Overview

Core Components

  1. Dashboard Service - Platform metrics and analytics aggregation
  2. User Management Service - User administration and impersonation
  3. AI Management Service - AI feature monitoring, prompt management, and cost tracking
  4. Waitlist Service - Waitlist signup tracking and conversion management
  5. Feature Flag Service - Feature toggle and rollout management
  6. Audit Service - Action logging and compliance tracking

Technology Stack

  • Framework: Next.js 15 with App Router (src/app structure)
  • Styling: Tailwind CSS with custom design system
  • Database: Supabase with admin service role
  • Authentication: Supabase Auth with cross-app session management
  • State Management: React hooks and client-side state
  • Icons: Lucide React for consistent iconography

📊 Dashboard Features

Main Dashboard (/dashboard)

The main dashboard provides real-time overview of platform metrics organized into sections:

Implemented Metrics:

  • User Metrics: Total users, active users (7d/30d), new users today
  • Content Metrics: Total campaigns, active campaigns, total stories, word count
  • Engagement Metrics: Total conversations, response rate, family members, invitations
  • Publishing & Media: Total books, books in progress, images, audio recordings
  • Business Metrics: Monthly revenue, subscription tier breakdown (starter/family/premium)
  • Waitlist Metrics: Total signups, verified users, conversion rate, free eligible count

Data Source:

// Dashboard service aggregates data from multiple tables
const stats = await dashboardService.getDashboardStats()
// Uses optimized API endpoint: /api/admin/stats/platform

Features:

  • Real-time activity feed showing recent user signups, campaigns, stories, and conversations
  • Quick action links to Users, Waitlist, Content Moderation, Feature Flags, and System Health
  • Color-coded stat cards with icons for easy scanning
  • Loading states with skeleton screens

👥 User Management (/dashboard/users)

User Administration Interface

Route: /dashboard/users

Features:

  • User list table with pagination (50 users per page)
  • Search by name or email
  • Filter by subscription tier (starter/family/premium)
  • Filter by status (trial/active/canceled/expired)
  • Display user profiles with full name, email, ID
  • Show subscription tier, trial end dates, last login, join date
  • Inline actions: Impersonate, View, Edit

Implemented Actions:

// User impersonation with token generation
const handleImpersonate = async (userId: string) => {
  const token = await userManagementService.createImpersonationToken(
    userId,
    'admin-user'
  )
  // Opens main app with impersonation token
  window.open(`${mainAppUrl}/auth-redirect?impersonate=${token}`, '_blank')
}

Stats Displayed:

  • Total Users
  • Active Users
  • Premium Users
  • Trial Users

🎭 User Impersonation (/dashboard/users/impersonate)

Impersonation System

Route: /dashboard/users/impersonate

Implementation:

  • Accessible from Users page via “Impersonate” button
  • Creates temporary impersonation tokens via userManagementService
  • Opens main web app in new tab with impersonation context
  • Token passed via query parameter: ?impersonate={token}

Service Methods:

// From user-management-service.ts
createImpersonationToken(userId: string, adminId: string): Promise<string>

Security:

  • Impersonation sessions are logged in audit tables
  • Tokens are temporary and single-use
  • Admin context maintained for audit trail
  • Clear visual indicators when impersonating in main app

🚩 Feature Flag Management (/dashboard/feature-flags)

Feature Flags Interface

Route: /dashboard/feature-flags

Features:

  • Create, edit, and delete feature flags
  • Toggle flags on/off with visual switch controls
  • Set rollout percentage (0-100%)
  • Configure environment (production/staging/development)
  • Add descriptions for documentation
  • Export configuration as TypeScript code
  • Sync with config files

Flag Properties:

interface FeatureFlag {
  id: string
  flag_name: string
  description: string | null
  is_enabled: boolean
  rollout_percentage: number
  environment: string
  created_at: string
  updated_at: string
}

API Integration:

  • GET/POST/PUT/DELETE /api/feature-flags
  • Real-time updates with toast notifications
  • Status badges: Enabled (green) / Disabled (red)
  • Rollout percentage badges with color coding

Export Feature:

  • Generate TypeScript const object from flags
  • Copy to clipboard functionality
  • Useful for syncing with application code

🤖 AI Management (/dashboard/ai-management)

AI Dashboard Overview

Route: /dashboard/ai-management

Key Features:

  • Time Range Selector: Today, 24h, 3d, 7d, 15d, 1m, 3m, 6m, 1y
  • Overview Stats: Total cost, requests, success rate, avg response time
  • Model Performance: Cost per request, success rates, usage counts
  • Feature Usage: Breakdown by AI feature (conversations, stories, etc.)
  • Top 5 Prompts: Most frequently used prompts with usage counts
  • Active Alerts: Cost warnings, performance issues, high usage notifications
  • Optimization Suggestions: Model cost comparisons and efficiency recommendations

Sub-Routes:

  • /dashboard/ai-management/analytics - Detailed analytics and charts
  • /dashboard/ai-management/features - AI feature configuration
  • /dashboard/ai-management/prompts - Prompt template management
  • /dashboard/ai-management/prompts/new - Create new prompts
  • /dashboard/ai-management/prompts/[id]/edit - Edit existing prompts
  • /dashboard/ai-management/prompts/[id]/history - Prompt version history
  • /dashboard/ai-management/voices - Voice/TTS settings

Service Integration:

// From ai-management.ts and ai-management-enhanced.ts
const aiService = getAIManagementService()
const overview = await getOverviewStatsForRange(timeRange)
const features = await aiService.getFeatureUsageStats(days)
const models = await aiService.getModelPerformanceStats(days)
const prompts = await aiService.getTopPromptTemplates(5)

📋 Waitlist Management (/dashboard/waitlist)

Waitlist System

Route: /dashboard/waitlist

Features:

  • Display all waitlist signups with pagination (50 per page)
  • Filter by status: pending, verified, contacted, converted
  • Filter by date range
  • Search by email or name
  • Bulk status updates
  • Individual status progression (Verify → Contact → Convert)
  • CSV export with full data
  • Free subscription eligibility tracking

Stats Cards:

  • Total Signups (with today’s count)
  • Verified Users (with pending count)
  • Conversion Rate (percentage and converted count)
  • Free Eligible (count vs limit)

Waitlist Entry Data:

interface WaitlistEntry {
  id: string
  email: string
  name?: string
  phone?: string
  status: 'pending' | 'verified' | 'contacted' | 'converted'
  utm_source?: string
  referral_source?: string
  landing_page?: string
  free_subscription_eligible: boolean
  verified_at?: string
  created_at: string
}

Service Methods:

// From waitlist-service.ts
getWaitlistStats(): Promise<WaitlistStats>
getWaitlistEntries(filters, page, limit): Promise<{entries, total}>
updateEntryStatus(entryId, status): Promise<void>
bulkUpdateStatus(entryIds, status): Promise<void>
exportWaitlist(filters): Promise<WaitlistEntry[]>

📝 Additional Admin Routes

Editor Management (/dashboard/editor)

Templates & Content Blocks:

  • /dashboard/editor/templates - Manage editor templates
  • /dashboard/editor/templates/new - Create new template
  • /dashboard/editor/templates/edit/[id] - Edit template
  • /dashboard/editor/content-blocks - Manage reusable content blocks

Email Management (/dashboard/email)

Email System:

  • /dashboard/email - Email dashboard
  • /dashboard/email/templates - Email template management
  • /dashboard/email/templates/new - Create email template
  • /dashboard/email/templates/[id]/edit - Edit email template
  • /dashboard/email/ab-test - A/B testing for emails

Tools & Testing (/dashboard/tools)

Admin Tools:

  • /dashboard/tools - Tools overview
  • /dashboard/tools/story-prompts/library - Story prompt library
  • /dashboard/tools/story-prompts/collections - Prompt collections
  • /dashboard/tools/story-prompts/analytics - Prompt analytics
  • /dashboard/tools/story-prompts/performance - Performance metrics
  • /dashboard/tools/story-prompts/bulk-operations - Bulk management
  • /dashboard/tools/book-blurb/samples/library - Book blurb samples
  • /dashboard/tools/book-blurb/samples/add - Add new samples
  • /dashboard/tools/book-blurb/samples/queue - Processing queue
  • /dashboard/tools/feedback-analytics - User feedback analytics

Conversation Testing (/dashboard/conversation-testing)

Testing Interface:

  • /dashboard/conversation-testing - Test conversations
  • /dashboard/conversation-testing/results - View test results
  • /dashboard/conversation-testing/analytics - Test analytics
  • /dashboard/conversation-testing/debug - Debug tools

📊 System & Other Routes

System Management (/dashboard/system)

System Tools:

  • /dashboard/system - System overview
  • /dashboard/system/database - Database management
  • /dashboard/system/feature-flags - System feature flags

Other Routes

Additional Features:

  • /dashboard/analytics - Platform analytics
  • /dashboard/billing - Billing management
  • /dashboard/content - Content oversight
  • /dashboard/conversations - Conversation logs
  • /dashboard/support - Support tools
  • /dashboard/user-support - User support interface
  • /dashboard/ai-providers - AI provider configuration
  • /dashboard/voice-settings - Voice/TTS settings
  • /dashboard/settings - Admin settings
  • /dashboard/resources - Resource management

🔐 API Routes

Admin API Endpoints

Statistics & Analytics:

  • GET /api/admin/stats/platform - Platform-wide statistics
  • GET /api/admin/stats/users - User statistics
  • GET /api/admin/stats/content - Content statistics

Feature Flags:

  • GET/POST/PUT/DELETE /api/feature-flags - Feature flag CRUD operations

Email System:

  • GET/POST /api/email/templates - Email template management
  • GET/PUT/DELETE /api/email/templates/[id] - Individual template operations
  • POST /api/email/send - Send emails
  • GET /api/email/analytics - Email analytics
  • GET/POST /api/email/ab-test - A/B testing management

Content & Tools:

  • GET/POST /api/content-blocks - Content block management

Testing & Debug:

  • GET /api/admin/test-conversations - Conversation testing
  • GET /api/admin/test-analytics - Test analytics
  • GET /api/admin/conversation-test-results - Test results
  • GET /api/admin/debug-test-data - Debug information
  • GET /api/test-env - Environment test

Utility:

  • POST /api/clear-cache - Clear application cache
  • GET /api/overview-stats - Overview statistics

🚀 Deployment & Environment

Environment Configuration

Required Environment Variables:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Cross-app Communication
NEXT_PUBLIC_MAIN_APP_URL=http://localhost:3000
NEXT_PUBLIC_WEB_APP_URL=http://localhost:3000
NEXT_PUBLIC_ADMIN_APP_URL=http://localhost:3003

Development Setup

Local Development:

# Navigate to admin app
cd apps/admin-app
 
# Ensure correct Node version
export PATH="/usr/local/opt/node@20/bin:$PATH"
 
# Install dependencies
npm install
 
# Start development server
npm run dev
# Runs on http://localhost:3003

Project Structure:

apps/admin-app/
├── src/
│   ├── app/              # Next.js App Router pages
│   │   ├── dashboard/    # Main dashboard routes
│   │   ├── api/          # API routes
│   │   └── page.tsx      # Root page
│   ├── components/       # React components
│   ├── lib/              # Services and utilities
│   │   ├── dashboard-service.ts
│   │   ├── user-management-service.ts
│   │   ├── ai-management.ts
│   │   ├── waitlist-service.ts
│   │   ├── feature-flag-service.ts
│   │   └── supabase.ts
│   └── scripts/          # Utility scripts
├── public/               # Static assets
└── package.json

🛠️ Services & Libraries

Core Services

Dashboard Service (lib/dashboard-service.ts)

  • Aggregates platform statistics
  • Fetches recent activity
  • System health monitoring
  • Uses optimized API endpoints

User Management Service (lib/user-management-service.ts)

  • User CRUD operations
  • Search and filtering
  • Impersonation token generation
  • User statistics

AI Management Service (lib/ai-management.ts, lib/ai-management-enhanced.ts)

  • AI usage tracking
  • Cost analysis
  • Model performance metrics
  • Feature usage statistics
  • Prompt template management

Waitlist Service (lib/waitlist-service.ts)

  • Waitlist entry management
  • Status tracking
  • Bulk operations
  • Export functionality

Feature Flag Service (lib/feature-flag-service.ts)

  • Flag CRUD operations
  • Environment configuration
  • Rollout percentage management

Key Libraries

  • React Hot Toast: Toast notifications (react-hot-toast)
  • Lucide React: Icon library for consistent UI
  • Tailwind CSS: Utility-first styling
  • Supabase Client: Database and auth integration

📚 Service API Reference

Dashboard Service Methods

// Get comprehensive dashboard statistics
getDashboardStats(): Promise<DashboardStats>
 
// Get recent platform activity
getRecentActivity(): Promise<RecentActivity[]>
 
// Get system health metrics
getSystemHealthMetrics(): Promise<SystemHealthMetric[]>

User Management Service Methods

// Get user statistics
getUserStats(): Promise<UserStats>
 
// Get filtered users with pagination
getUsers(filters: UserFilters, page: number, limit: number): Promise<{
  users: UserProfile[]
  total: number
  hasMore: boolean
}>
 
// Create impersonation token
createImpersonationToken(userId: string, adminId: string): Promise<string>

AI Management Service Methods

// Get overview statistics for time range
getOverviewStatsForRange(timeRange: string): Promise<TimeRangeStats>
 
// Get feature usage statistics
getFeatureUsageStats(days: number): Promise<FeatureUsageStats[]>
 
// Get model performance metrics
getModelPerformanceStats(days: number): Promise<ModelPerformanceStats[]>
 
// Get top prompt templates by usage
getTopPromptTemplates(limit: number): Promise<PromptTemplate[]>
 
// Get all prompt templates
getPromptTemplates(): Promise<PromptTemplate[]>
 
// Get AI features configuration
getFeatures(): Promise<AIFeature[]>

Waitlist Service Methods

// Get waitlist statistics
getWaitlistStats(): Promise<WaitlistStats>
 
// Get filtered waitlist entries with pagination
getWaitlistEntries(
  filters: WaitlistFilters,
  page: number,
  limit: number
): Promise<{ entries: WaitlistEntry[]; total: number }>
 
// Update single entry status
updateEntryStatus(entryId: string, status: WaitlistEntry['status']): Promise<void>
 
// Bulk update status
bulkUpdateStatus(entryIds: string[], status: WaitlistEntry['status']): Promise<void>
 
// Export waitlist data
exportWaitlist(filters: WaitlistFilters): Promise<WaitlistEntry[]>

🔄 Best Practices

Data Loading Patterns

  1. Optimized Queries: Use aggregation APIs (/api/admin/stats/platform)
  2. Pagination: Limit data fetched per request (50 items standard)
  3. Loading States: Show skeleton screens during data fetch
  4. Error Handling: Graceful fallbacks with user-friendly messages
  5. Parallel Fetching: Load independent data sources simultaneously

UI/UX Patterns

  1. Color Coding: Consistent color schemes for status badges
  2. Icon Usage: Lucide React icons for visual consistency
  3. Responsive Design: Mobile-friendly tables and cards
  4. Toast Notifications: User feedback for actions
  5. Search Debouncing: Prevent excessive API calls

Security Considerations

  1. Service Role Access: Admin app uses Supabase service role for elevated permissions
  2. Impersonation Logging: All impersonation sessions tracked
  3. Token Expiration: Temporary tokens for sensitive operations
  4. Environment Separation: Different configs for dev/staging/prod

🚨 Troubleshooting

Common Issues

Dashboard Not Loading:

  • Check Supabase connection in console
  • Verify environment variables are set correctly
  • Check browser console for API errors
  • Ensure service role key has proper permissions

User Impersonation Fails:

  • Verify NEXT_PUBLIC_MAIN_APP_URL is correct
  • Check impersonation token generation
  • Ensure main app accepts impersonation parameter
  • Review browser popup blockers

AI Management Shows No Data:

  • Verify time range selection
  • Check that AI usage tracking is enabled
  • Ensure database tables exist: ai_usage_logs, prompt_templates
  • Look for empty state messages (may indicate no activity in period)

Waitlist Export Not Working:

  • Check browser download permissions
  • Verify CSV generation logic
  • Ensure data is being fetched correctly

Development Tips

Hot Reload Issues:

# Clear Next.js cache
rm -rf .next
npm run dev

Database Connection Issues:

  • Check .env.local file exists and has correct values
  • Verify Supabase project is active
  • Test connection with simple query in browser console

Type Errors:

  • Run npm run type-check to see all TypeScript errors
  • Regenerate types from Supabase if schema changed

📈 Key Features Summary

Implemented Routes (52 total pages)

Main Sections:

  • Dashboard Overview
  • User Management (with impersonation)
  • AI Management (6 sub-pages)
  • Waitlist Management
  • Feature Flags
  • Editor Tools (4 sub-pages)
  • Email Management (5 sub-pages)
  • Testing Tools (4 sub-pages)
  • Story Prompt Tools (5 sub-pages)
  • System Management (3 sub-pages)
  • Various support and utility pages

API Endpoints: 29+ routes for data operations

Services: 6 core service modules managing different aspects of the platform

This admin dashboard provides comprehensive control over the MyStoryFlow platform with real-time monitoring, user management, AI optimization, and content oversight capabilities.