biblical-guide.com/admin-dashboard-implementation-plan.md

Biblical Guide Admin Dashboard - Implementation Plan

Current Application Analysis

Existing Infrastructure

• Framework: Next.js 15 with App Router
• Database: PostgreSQL with Prisma ORM
• Authentication: Custom JWT-based auth system
• UI: Tailwind CSS + shadcn/ui (main app) + MUI (admin dashboard)
• Internationalization: next-intl (English/Romanian)
• Deployment: PM2 with production build

Current Database Schema

The app already has a solid foundation with these models:

• User (with role field supporting "admin", "moderator", "user")
• Session (JWT token management)
• ChatConversation & ChatMessage (AI chat system)
• PrayerRequest & Prayer (prayer wall functionality)
• Bookmark & ChapterBookmark (user bookmarks)
• BiblePassage (Bible content with embeddings)
• ReadingHistory (user activity tracking)

Existing API Endpoints

• Authentication: /api/auth/*
• Bible operations: /api/bible/*
• Chat system: /api/chat/*
• Prayer wall: /api/prayers/*
• User management: /api/user/*
• Health check: /api/health

Implementation Plan

Phase 1: Foundation (Week 1)

1.1 Admin Authentication & Authorization

New API Routes:

• POST /api/admin/auth/login - Admin login (separate from user login)
• POST /api/admin/auth/logout - Admin logout
• GET /api/admin/auth/me - Get current admin info

Database Changes:

-- Add admin-specific fields to User model
ALTER TABLE "User" ADD COLUMN "adminCreatedAt" TIMESTAMP;
ALTER TABLE "User" ADD COLUMN "adminLastLogin" TIMESTAMP;
ALTER TABLE "User" ADD COLUMN "adminPermissions" TEXT[]; -- ['users', 'content', 'system']

-- Create audit log table
CREATE TABLE "AdminAuditLog" (
  "id" TEXT NOT NULL PRIMARY KEY,
  "adminId" TEXT NOT NULL,
  "action" TEXT NOT NULL,
  "resource" TEXT NOT NULL,
  "resourceId" TEXT,
  "details" JSONB,
  "ipAddress" TEXT,
  "userAgent" TEXT,
  "createdAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY ("adminId") REFERENCES "User"("id") ON DELETE CASCADE
);

-- Create settings table
CREATE TABLE "AppSettings" (
  "id" TEXT NOT NULL PRIMARY KEY,
  "key" TEXT NOT NULL UNIQUE,
  "value" JSONB NOT NULL,
  "updatedBy" TEXT NOT NULL,
  "updatedAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY ("updatedBy") REFERENCES "User"("id")
);

Components to Create:

• /app/admin/login/page.tsx - Admin login page
• /components/admin/auth/admin-login-form.tsx
• /components/admin/layout/admin-layout.tsx
• /lib/admin-auth.ts - Admin authentication utilities

1.2 Basic Admin Dashboard Layout

New Pages:

• /app/admin/page.tsx - Dashboard overview
• /app/admin/layout.tsx - Admin layout with navigation

Components:

• /components/admin/dashboard/overview-cards.tsx
• /components/admin/layout/sidebar-nav.tsx
• /components/admin/layout/header.tsx

1.3 Dashboard Overview (Read-only)

Metrics Cards:

• Total users count
• Daily active users (last 24h login)
• AI conversations today
• Prayer requests today

API Routes:

• GET /api/admin/stats/overview - Basic dashboard metrics
• GET /api/admin/stats/users - User statistics

Phase 2: User Management (Week 2)

2.1 User Management Interface

New Pages:

• /app/admin/users/page.tsx - User list and search
• /app/admin/users/[id]/page.tsx - User detail view

API Routes:

• GET /api/admin/users - List users with filtering
• GET /api/admin/users/[id] - Get user details
• PUT /api/admin/users/[id]/status - Update user status (suspend/ban)
• DELETE /api/admin/users/[id] - Delete user (GDPR)
• POST /api/admin/users/[id]/reset-password - Force password reset

Components:

• /components/admin/users/user-table.tsx
• /components/admin/users/user-filters.tsx
• /components/admin/users/user-detail-modal.tsx
• /components/admin/users/user-actions.tsx

2.2 Content Moderation

Database Schema Addition:

-- Add moderation fields to PrayerRequest
ALTER TABLE "PrayerRequest" ADD COLUMN "moderationStatus" TEXT DEFAULT 'pending'; -- pending, approved, rejected
ALTER TABLE "PrayerRequest" ADD COLUMN "moderatedBy" TEXT;
ALTER TABLE "PrayerRequest" ADD COLUMN "moderatedAt" TIMESTAMP;
ALTER TABLE "PrayerRequest" ADD COLUMN "moderationNote" TEXT;

-- Create content reports table
CREATE TABLE "ContentReport" (
  "id" TEXT NOT NULL PRIMARY KEY,
  "reporterId" TEXT,
  "contentType" TEXT NOT NULL, -- 'prayer', 'chat'
  "contentId" TEXT NOT NULL,
  "reason" TEXT NOT NULL,
  "description" TEXT,
  "status" TEXT DEFAULT 'pending', -- pending, resolved, dismissed
  "resolvedBy" TEXT,
  "resolvedAt" TIMESTAMP,
  "createdAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY ("reporterId") REFERENCES "User"("id"),
  FOREIGN KEY ("resolvedBy") REFERENCES "User"("id")
);

New Pages:

• /app/admin/moderation/page.tsx - Moderation queue
• /app/admin/moderation/prayers/page.tsx - Prayer moderation

API Routes:

• GET /api/admin/moderation/prayers - Get prayers pending moderation
• PUT /api/admin/moderation/prayers/[id] - Approve/reject prayer
• GET /api/admin/moderation/reports - Get content reports

Phase 3: Analytics & Monitoring (Week 3)

3.1 Analytics Dashboard

New Pages:

• /app/admin/analytics/page.tsx - Analytics overview
• /app/admin/analytics/users/page.tsx - User analytics
• /app/admin/analytics/engagement/page.tsx - Engagement metrics

API Routes:

• GET /api/admin/analytics/users - User growth, retention metrics
• GET /api/admin/analytics/conversations - Chat analytics
• GET /api/admin/analytics/prayers - Prayer wall analytics
• GET /api/admin/analytics/bible-usage - Bible reading stats

Components:

• /components/admin/analytics/growth-chart.tsx (using MUI X Charts)
• /components/admin/analytics/engagement-metrics.tsx
• /components/admin/analytics/user-segments.tsx

3.2 AI Chat Monitoring

Database Schema Addition:

-- Add monitoring fields to ChatConversation
ALTER TABLE "ChatConversation" ADD COLUMN "tokensUsed" INTEGER DEFAULT 0;
ALTER TABLE "ChatConversation" ADD COLUMN "costEstimate" DECIMAL(10,4);
ALTER TABLE "ChatConversation" ADD COLUMN "flagged" BOOLEAN DEFAULT FALSE;
ALTER TABLE "ChatConversation" ADD COLUMN "flagReason" TEXT;

-- Create AI usage tracking
CREATE TABLE "AIUsageLog" (
  "id" TEXT NOT NULL PRIMARY KEY,
  "conversationId" TEXT,
  "model" TEXT NOT NULL,
  "inputTokens" INTEGER NOT NULL,
  "outputTokens" INTEGER NOT NULL,
  "cost" DECIMAL(10,4) NOT NULL,
  "responseTime" INTEGER, -- milliseconds
  "createdAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY ("conversationId") REFERENCES "ChatConversation"("id")
);

New Pages:

• /app/admin/chat/page.tsx - Chat monitoring overview
• /app/admin/chat/conversations/page.tsx - Live conversation feed
• /app/admin/chat/costs/page.tsx - Cost tracking

API Routes:

• GET /api/admin/chat/overview - Chat usage metrics
• GET /api/admin/chat/conversations - Recent conversations
• GET /api/admin/chat/costs - Cost analysis
• PUT /api/admin/chat/conversations/[id]/flag - Flag conversation

Phase 4: System Administration (Week 4)

4.1 System Settings & Configuration

New Pages:

• /app/admin/settings/page.tsx - App settings
• /app/admin/settings/features/page.tsx - Feature toggles
• /app/admin/settings/admins/page.tsx - Admin user management

API Routes:

• GET /api/admin/settings - Get all settings
• PUT /api/admin/settings - Update settings
• GET /api/admin/system/health - System health check
• POST /api/admin/system/maintenance - Toggle maintenance mode

Settings Schema:

interface AppSettings {
  siteName: string;
  supportEmail: string;
  aiChatEnabled: boolean;
  prayerWallEnabled: boolean;
  userRegistrationOpen: boolean;
  dailyVerseEnabled: boolean;
  aiModel: 'gpt-4' | 'gpt-3.5-turbo';
  maxChatsPerUserPerDay: number;
  maintenanceMode: boolean;
}

4.2 Communications

Database Schema:

CREATE TABLE "EmailTemplate" (
  "id" TEXT NOT NULL PRIMARY KEY,
  "key" TEXT NOT NULL UNIQUE,
  "subject" TEXT NOT NULL,
  "bodyHtml" TEXT NOT NULL,
  "bodyText" TEXT NOT NULL,
  "variables" TEXT[], -- Available template variables
  "updatedBy" TEXT NOT NULL,
  "updatedAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY ("updatedBy") REFERENCES "User"("id")
);

CREATE TABLE "EmailCampaign" (
  "id" TEXT NOT NULL PRIMARY KEY,
  "name" TEXT NOT NULL,
  "subject" TEXT NOT NULL,
  "bodyHtml" TEXT NOT NULL,
  "targetSegment" TEXT NOT NULL, -- 'all', 'active', 'dormant'
  "status" TEXT DEFAULT 'draft', -- draft, scheduled, sending, sent
  "scheduledAt" TIMESTAMP,
  "sentAt" TIMESTAMP,
  "recipientCount" INTEGER DEFAULT 0,
  "createdBy" TEXT NOT NULL,
  "createdAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY ("createdBy") REFERENCES "User"("id")
);

New Pages:

• /app/admin/communications/page.tsx - Email campaigns
• /app/admin/communications/templates/page.tsx - Email templates

Technical Implementation Details

Authentication Flow

1. Admin Login: Separate from user login, checks role field
2. JWT Enhancement: Include admin permissions in token
3. Route Protection: Middleware checks for admin role
4. Audit Logging: Log all admin actions automatically

Database Migrations

// prisma/migrations/add-admin-features.sql
-- Run the SQL statements from each phase above

Middleware Enhancement

// Update middleware.ts
const adminPaths = ['/admin'];
const isAdminPath = adminPaths.some(path =>
  request.nextUrl.pathname.startsWith(path)
);

if (isAdminPath) {
  // Check for admin authentication
  // Verify admin role and permissions
}

API Response Standards

// Standard admin API response format
interface AdminApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
  pagination?: {
    page: number;
    limit: number;
    total: number;
  };
}

Real-time Features

• WebSocket Integration: Extend existing WebSocket for admin notifications
• Auto-refresh: Key metrics update every 30 seconds
• Live Activity Feed: Real-time user actions display

Security Implementation

Access Control

// lib/admin-permissions.ts
export enum AdminPermission {
  VIEW_USERS = 'users:read',
  MANAGE_USERS = 'users:write',
  MODERATE_CONTENT = 'content:moderate',
  VIEW_ANALYTICS = 'analytics:read',
  MANAGE_SYSTEM = 'system:manage'
}

export function hasPermission(user: User, permission: AdminPermission): boolean {
  if (user.role === 'admin') return true; // Super admin
  return user.adminPermissions?.includes(permission) || false;
}

Audit Logging

// lib/admin-audit.ts
export async function logAdminAction(
  adminId: string,
  action: string,
  resource: string,
  resourceId?: string,
  details?: any,
  request?: Request
) {
  await prisma.adminAuditLog.create({
    data: {
      adminId,
      action,
      resource,
      resourceId,
      details,
      ipAddress: getClientIP(request),
      userAgent: request?.headers.get('user-agent')
    }
  });
}

File Structure

app/
├── admin/
│   ├── layout.tsx
│   ├── page.tsx                    # Dashboard overview
│   ├── login/
│   │   └── page.tsx               # Admin login
│   ├── users/
│   │   ├── page.tsx               # User management
│   │   └── [id]/
│   │       └── page.tsx           # User details
│   ├── moderation/
│   │   ├── page.tsx               # Moderation queue
│   │   └── prayers/
│   │       └── page.tsx           # Prayer moderation
│   ├── analytics/
│   │   ├── page.tsx               # Analytics overview
│   │   ├── users/
│   │   │   └── page.tsx           # User analytics
│   │   └── engagement/
│   │       └── page.tsx           # Engagement metrics
│   ├── chat/
│   │   ├── page.tsx               # Chat monitoring
│   │   ├── conversations/
│   │   │   └── page.tsx           # Live conversations
│   │   └── costs/
│   │       └── page.tsx           # Cost tracking
│   ├── settings/
│   │   ├── page.tsx               # App settings
│   │   ├── features/
│   │   │   └── page.tsx           # Feature toggles
│   │   └── admins/
│   │       └── page.tsx           # Admin management
│   └── communications/
│       ├── page.tsx               # Email campaigns
│       └── templates/
│           └── page.tsx           # Email templates
├── api/
│   └── admin/
│       ├── auth/
│       ├── users/
│       ├── moderation/
│       ├── analytics/
│       ├── chat/
│       ├── settings/
│       └── communications/
components/
└── admin/
    ├── auth/
    ├── layout/
    ├── dashboard/
    ├── users/
    ├── moderation/
    ├── analytics/
    ├── chat/
    ├── settings/
    └── communications/
lib/
├── admin-auth.ts
├── admin-permissions.ts
├── admin-audit.ts
└── admin-utils.ts

Next Steps

1. Phase 1 Setup (Week 1):

   • Create admin authentication system
   • Build basic dashboard layout
   • Implement overview metrics

2. Progressive Enhancement (Weeks 2-4):

   • Add user management features
   • Implement content moderation
   • Build analytics dashboard
   • Add system administration tools

3. Testing & Security:

   • Unit tests for admin functions
   • Security audit of admin routes
   • Performance testing with large datasets

4. Documentation:

   • Admin user guide
   • API documentation for admin endpoints
   • Deployment and maintenance procedures

MUI Integration for Admin Dashboard

Required MUI Packages

npm install @mui/material @emotion/react @emotion/styled
npm install @mui/x-data-grid @mui/x-charts @mui/x-date-pickers
npm install @mui/icons-material @mui/lab
npm install @fontsource/roboto # MUI default font

Admin Theme Configuration

// lib/admin-theme.ts
import { createTheme } from '@mui/material/styles';

export const adminTheme = createTheme({
  palette: {
    mode: 'light',
    primary: {
      main: '#1976d2', // Professional blue
      contrastText: '#ffffff'
    },
    secondary: {
      main: '#dc004e',
    },
    background: {
      default: '#f5f5f5',
      paper: '#ffffff'
    },
    grey: {
      100: '#f5f5f5',
      200: '#eeeeee',
      300: '#e0e0e0',
      400: '#bdbdbd',
      500: '#9e9e9e'
    }
  },
  typography: {
    fontFamily: ['Roboto', 'Arial', 'sans-serif'].join(','),
    h4: {
      fontWeight: 600,
      fontSize: '1.5rem'
    },
    h6: {
      fontWeight: 500,
      fontSize: '1.125rem'
    }
  },
  components: {
    MuiCard: {
      styleOverrides: {
        root: {
          boxShadow: '0 2px 8px rgba(0,0,0,0.1)',
          borderRadius: 8
        }
      }
    },
    MuiDataGrid: {
      styleOverrides: {
        root: {
          border: 'none',
          '& .MuiDataGrid-cell': {
            borderBottom: '1px solid #f0f0f0'
          }
        }
      }
    }
  }
});

Key MUI Components for Admin Features

Dashboard Overview

• MUI Card + CardContent for metrics cards
• MUI Typography for headings and stats
• MUI Chip for status indicators
• MUI LinearProgress for loading states

User Management

• MUI Data Grid with server-side pagination, sorting, filtering
• MUI Avatar for user profile pictures
• MUI Chip for user status (Active, Suspended, etc.)
• MUI IconButton for quick actions (View, Edit, Ban)
• MUI Dialog for user detail modals

Content Moderation

• MUI List + ListItem for moderation queue
• MUI Accordion for expandable prayer requests
• MUI ButtonGroup for Approve/Reject actions
• MUI Badge for pending counts

Analytics Dashboard

• MUI X Charts (LineChart, BarChart, PieChart) for visualizations
• MUI DatePicker for date range selection
• MUI Select for metric filtering
• MUI Grid for responsive chart layout

System Administration

• MUI Switch for feature toggles
• MUI Slider for numeric settings (rate limits)
• MUI TextField for configuration values
• MUI Alert for system status messages

Admin Layout Components

// components/admin/layout/admin-layout.tsx
import { ThemeProvider } from '@mui/material/styles';
import { CssBaseline, Box, Drawer, AppBar, Toolbar } from '@mui/material';
import { adminTheme } from '@/lib/admin-theme';

export function AdminLayout({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider theme={adminTheme}>
      <CssBaseline />
      <Box sx={{ display: 'flex' }}>
        <AppBar position="fixed">
          <Toolbar>
            {/* Admin header */}
          </Toolbar>
        </AppBar>
        <Drawer variant="permanent">
          {/* Admin navigation */}
        </Drawer>
        <Box component="main" sx={{ flexGrow: 1, p: 3, mt: 8 }}>
          {children}
        </Box>
      </Box>
    </ThemeProvider>
  );
}

Data Grid Configuration Example

// components/admin/users/user-data-grid.tsx
import { DataGrid, GridColDef, GridActionsCellItem } from '@mui/x-data-grid';
import { Chip, Avatar } from '@mui/material';
import { Visibility, Block, Delete } from '@mui/icons-material';

const columns: GridColDef[] = [
  {
    field: 'avatar',
    headerName: '',
    width: 60,
    renderCell: (params) => <Avatar src={params.value} />,
    sortable: false,
    filterable: false
  },
  { field: 'email', headerName: 'Email', width: 250 },
  { field: 'name', headerName: 'Name', width: 200 },
  { field: 'createdAt', headerName: 'Joined', width: 120, type: 'date' },
  { field: 'lastLoginAt', headerName: 'Last Active', width: 120, type: 'dateTime' },
  {
    field: 'role',
    headerName: 'Status',
    width: 120,
    renderCell: (params) => (
      <Chip
        label={params.value}
        color={params.value === 'active' ? 'success' : 'default'}
        size="small"
      />
    )
  },
  {
    field: 'actions',
    type: 'actions',
    headerName: 'Actions',
    width: 120,
    getActions: (params) => [
      <GridActionsCellItem icon={<Visibility />} label="View" />,
      <GridActionsCellItem icon={<Block />} label="Suspend" />,
      <GridActionsCellItem icon={<Delete />} label="Delete" />
    ]
  }
];

Chart Configuration Example

// components/admin/analytics/user-growth-chart.tsx
import { LineChart } from '@mui/x-charts/LineChart';
import { Card, CardHeader, CardContent } from '@mui/material';

export function UserGrowthChart({ data }: { data: any[] }) {
  return (
    <Card>
      <CardHeader title="User Growth" />
      <CardContent>
        <LineChart
          width={600}
          height={300}
          series={[
            {
              data: data.map(d => d.users),
              label: 'Total Users',
              color: '#1976d2'
            }
          ]}
          xAxis={[
            {
              scaleType: 'point',
              data: data.map(d => d.date)
            }
          ]}
        />
      </CardContent>
    </Card>
  );
}

This implementation plan leverages the existing robust infrastructure while adding comprehensive admin capabilities using MUI components for a professional, consistent admin interface, ensuring minimal disruption to the current application.