biblical-guide.com/README.md

# Biblical Guide - Complete Web Application

A comprehensive web application for Bible study with AI chat capabilities, real-time features, and a complete administrative dashboard.

## 🚀 Complete Features

### 📖 **Advanced Bible Reader**
- Responsive Scripture navigation with modern UI
- Verse bookmarking system with customizable colors
- Reading history with automatic synchronization
- Intelligent caching for optimal performance
- Full-text search with PostgreSQL GIN indexing

### 🤖 **Specialized AI Chat Assistant**
- AI assistant trained for biblical and theological questions
- Azure OpenAI integration with Ollama fallback support
- Responses in multiple languages with scriptural references
- Automatic conversation saving for authenticated users
- Context-aware biblical guidance

### 🙏 **Real-time Prayer Wall**
- Community prayer request sharing
- Real-time prayer counter system
- Anonymous and named posting options
- Optimistic UI with automatic updates
- Prayer request categorization and moderation

### 🔧 **Comprehensive Admin Dashboard**
Complete administrative control panel with four main sections:

#### **📊 Dashboard Overview**
- Real-time system metrics and key performance indicators
- User activity monitoring and engagement statistics
- Content creation and interaction analytics
- Quick access to critical administrative functions

#### **👥 User Management**
- Advanced user data grid with search and filtering
- User role management (admin, moderator, user, suspended)
- Detailed user profiles with activity summaries
- User actions: view, suspend, activate, promote, delete
- Bulk operations and user analytics

#### **🛡️ Content Moderation**
- Prayer request approval/rejection workflows
- Automated content filtering and flagging
- Conversation monitoring with content analysis
- Moderation queue management
- Community guideline enforcement

#### **📈 Analytics & Insights**
- Interactive charts and real-time statistics
- User behavior analysis and retention metrics
- Content engagement tracking and trends
- System performance monitoring
- Custom reporting and data visualization

#### **⚙️ System Administration**
- Real-time system health monitoring
- Database backup and restore functionality
- Security oversight and threat detection
- System configuration management
- Performance optimization tools

### 🔍 **Advanced Search with Full-Text**
- PostgreSQL GIN indexing for lightning-fast searches
- Similarity search with intelligent ranking
- Optimized results with caching and high performance
- Support for complex queries and regular expressions

### 🔐 **Robust Security System**
- JWT authentication with advanced validation
- Rate limiting per endpoint and user
- Security middleware with CSRF/XSS protection
- Input validation with Zod schemas
- Role-based access control for admin features

### 📊 **Performance & Monitoring**
- Cache layer with PostgreSQL UNLOGGED tables
- Optimization and automatic maintenance scripts
- Performance monitoring with detailed reports
- Optimized indexes for rapid searches

## Technologies Used

- **Frontend**: Next.js 15.5.3 (App Router), TypeScript, Material-UI (MUI), Recharts
- **Backend**: Next.js API Routes, PostgreSQL with extensions
- **Database**: PostgreSQL 16 with pgvector, pg_trgm, full-text search
- **AI**: Azure OpenAI API with fallback to Ollama
- **Security**: JWT, bcrypt, rate limiting, input validation
- **Admin Dashboard**: Material-UI DataGrid, Charts, Real-time monitoring
- **DevOps**: PM2, SSL support, automated deployment
- **Performance**: Caching, indexing, optimization scripts

## Quick Installation

### Using PM2 (Recommended)

1. Clone the repository:
```bash
git clone https://git.noru1.ro/andrei/biblical-guide.com.git
cd biblical-guide
```

2. Copy configuration file:
```bash
cp .env.example .env.local
```

3. Edit `.env.local` with your values:
```env
DATABASE_URL=postgresql://postgres:password@localhost:5432/biblical-guide
AZURE_OPENAI_KEY=your-azure-key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_DEPLOYMENT=gpt-4
JWT_SECRET=your-secure-jwt-secret
NEXTAUTH_SECRET=your-secure-nextauth-secret
NEXTAUTH_URL=https://biblical-guide.com
```

4. Install dependencies and build:
```bash
npm ci
npm run build
```

5. Run migrations and import biblical data:
```bash
npx prisma migrate deploy
npx prisma generate
npm run import-bible
```

6. Start application with PM2:
```bash
pm2 start ecosystem.config.js --env production
```

7. Access the application at: http://localhost:3010

### Admin Dashboard Access

1. Create an admin user in the database:
```sql
UPDATE users SET role = 'admin' WHERE email = 'your-email@domain.com';
```

2. Access admin dashboard at: `/admin`

3. Use your user credentials to log in to the admin panel

## Admin Dashboard Features

### 🎯 **Dashboard Overview** (`/admin`)
- System health indicators and real-time metrics
- User activity statistics and growth tracking
- Content creation and engagement analytics
- Quick navigation to all administrative functions

### 👥 **User Management** (`/admin/users`)
- Complete user lifecycle management
- Advanced filtering and search capabilities
- User role assignment and permissions
- Activity monitoring and user analytics
- Bulk operations and data export

### 🛡️ **Content Moderation** (`/admin/content`)
- Prayer request moderation queue
- Automated content filtering
- Community guideline enforcement
- Approval/rejection workflows
- Content analytics and reporting

### 💬 **Chat Monitoring** (`/admin/chat`)
- Conversation oversight and analysis
- Message content filtering
- User interaction monitoring
- Automated moderation alerts
- Chat statistics and insights

### 📊 **Analytics Dashboard** (`/admin/analytics`)
- Comprehensive system analytics with interactive charts
- User behavior analysis and retention metrics
- Content performance tracking
- Real-time statistics and trends
- Custom reporting capabilities

### ⚙️ **System Administration** (`/admin/settings`)
- Real-time system health monitoring
- Database backup and restore
- Security status overview
- Performance metrics
- System configuration management

## Available Scripts

- `npm run dev` - Start development server
- `npm run build` - Build application for production
- `npm run start` - Start production application
- `npm run lint` - Check code with ESLint
- `npm run typecheck` - Run TypeScript type checking
- `npm run import-bible` - Import biblical data to database

## Project Structure

```
├── app/                    # Next.js App Router
│   ├── admin/             # Admin dashboard pages
│   │   ├── analytics/     # Analytics and reporting
│   │   ├── chat/          # Chat monitoring
│   │   ├── content/       # Content moderation
│   │   ├── settings/      # System administration
│   │   └── users/         # User management
│   ├── api/               # API Routes
│   │   ├── admin/         # Admin API endpoints
│   │   ├── auth/          # Authentication
│   │   ├── bible/         # Bible data
│   │   ├── chat/          # Chat functionality
│   │   └── prayers/       # Prayer requests
│   └── [locale]/          # Internationalized pages
├── components/             # React Components
│   ├── admin/             # Admin dashboard components
│   │   ├── analytics/     # Analytics components
│   │   ├── chat/          # Chat monitoring
│   │   ├── content/       # Content moderation
│   │   ├── layout/        # Admin layout
│   │   ├── system/        # System administration
│   │   └── users/         # User management
│   ├── auth/              # Authentication components
│   ├── bible/             # Bible reading components
│   ├── chat/              # AI chat interface
│   ├── prayer/            # Prayer components
│   └── ui/                # General UI components
├── lib/                   # Utilities and configurations
│   ├── admin-auth.ts      # Admin authentication
│   ├── auth.ts            # User authentication
│   ├── db.ts              # Database connection
│   └── validation.ts      # Input validation schemas
├── prisma/                # Prisma schema and migrations
└── ecosystem.config.js    # PM2 configuration
```

## Admin Authentication

The admin dashboard uses a separate authentication system from the main application:

1. **Admin Login**: `/admin/login`
2. **Role-based Access**: Admin and moderator roles supported
3. **Secure Sessions**: JWT tokens with 8-hour expiration
4. **Permission System**: Granular permissions for different admin functions

## Production Deployment

### Using PM2

1. Configure environment variables for production
2. Run deployment:
```bash
npm ci
npm run build
pm2 restart biblical-guide
pm2 save
```

### SSL Configuration

For HTTPS using Let's Encrypt:

```bash
# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Obtain SSL certificate
sudo certbot --nginx -d yourdomain.com
```

## Monitoring & Health Checks

- **Application Health**: `/api/health`
- **Admin System Health**: `/api/admin/system/health` (requires admin auth)
- **Logs**: `pm2 logs biblical-guide`
- **Real-time Monitoring**: Available in admin dashboard

## Security Features

- **JWT Authentication** with secure token management
- **Role-based Access Control** for admin features
- **Rate Limiting** on API endpoints
- **Input Validation** with Zod schemas
- **CSRF Protection** and XSS prevention
- **Content Filtering** and automated moderation
- **Secure Admin Sessions** with separate authentication

## API Endpoints

### Public APIs
- `/api/auth/*` - User authentication
- `/api/bible/*` - Bible data and search
- `/api/prayers/*` - Prayer requests
- `/api/chat/*` - AI chat functionality

### Admin APIs (Authentication Required)
- `/api/admin/auth/*` - Admin authentication
- `/api/admin/users/*` - User management
- `/api/admin/content/*` - Content moderation
- `/api/admin/chat/*` - Chat monitoring
- `/api/admin/analytics/*` - System analytics
- `/api/admin/system/*` - System administration

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b new-feature`
3. Commit changes: `git commit -m 'Add new feature'`
4. Push to branch: `git push origin new-feature`
5. Open a Pull Request

## License

This project is licensed under the MIT License.

## Support

For questions or issues, please open an issue on the repository.

---

*Built with ❤️ for the Christian community*

## Recent Updates

### v2.0.0 - Complete Admin Dashboard
- **Four-phase admin dashboard implementation**
- **User management system** with advanced data grids
- **Content moderation workflows** for prayer requests
- **Chat monitoring and analysis** with automated filtering
- **Comprehensive analytics** with interactive charts
- **System administration panel** with health monitoring
- **Real-time statistics** and performance tracking
- **Backup and restore functionality**
- **Security monitoring and alerts**
- **Professional Material-UI design** throughout admin interface

### v1.5.0 - Enhanced Features
- **Internationalization support** (English/Romanian)
- **Advanced search capabilities** with full-text indexing
- **Real-time prayer wall** with community features
- **Optimized performance** and caching
- **Security enhancements** and rate limiting

The Biblical Guide application now provides a complete platform for Bible study, community prayer, AI-assisted learning, and comprehensive administrative management.