biblical-guide.com/BACKEND_ARCHITECTURE_ANALYSIS.md

Biblical Guide - Backend Architecture Analysis

Executive Summary

The Biblical Guide application is a comprehensive Next.js-based web application with a sophisticated backend architecture designed to support Bible reading, prayer requests, AI chat, user management, and a full admin panel. The backend utilizes PostgreSQL for persistent storage, JWT for authentication, Stripe for payments/subscriptions, and various third-party integrations.

---

1. DATABASE SCHEMA & MODELS

Database Provider

• Type: PostgreSQL
• ORM: Prisma 6.16.2
• Connection: Via DATABASE_URL environment variable
• Total Models: 32 core data models

Core Data Models

User Management

User

• Unique fields: id, email
• Authentication: passwordHash
• Profile: name, role ("user", "admin", "moderator"), theme, fontSize, favoriteBibleVersion
• Subscription: subscriptionTier ("free", "premium"), subscriptionStatus, conversationLimit, conversationCount, limitResetDate
• Stripe Integration: stripeCustomerId, stripeSubscriptionId
• Tracking: createdAt, updatedAt, lastLoginAt
• Relationships: 14 one-to-many relationships (sessions, bookmarks, notes, highlights, etc.)
• Indexes: on role, subscriptionTier, stripeCustomerId

Session

• Fields: id, userId, token (unique), expiresAt, createdAt
• 7-day token expiration
• Cascade delete when user deleted
• Indexes: on userId, token

Bible Data Models

BibleVersion

• Fields: id, name, abbreviation, language, description, country, englishTitle, flagImageUrl, zipFileUrl, isDefault
• Composite unique constraint: abbreviation + language
• Supports multi-language Bible versions
• Indexes: on language, isDefault, and composite index (language, isDefault)

BibleBook

• Fields: id, versionId, name, testament, orderNum, bookKey (cross-version matching)
• Links to BibleVersion
• Unique constraints: (versionId, orderNum) and (versionId, bookKey)
• Indexes: on versionId, testament

BibleChapter

• Fields: id, bookId, chapterNum
• Unique constraint: (bookId, chapterNum)
• Index: on bookId

BibleVerse

• Fields: id, chapterId, verseNum, text (Text type)
• Unique constraint: (chapterId, verseNum)
• Index: on chapterId

BiblePassage (Legacy/Embedding Search)

• Fields: id, testament, book, chapter, verse, ref, lang, translation, textRaw, textNorm, embedding (vector)
• Used for AI embedding search functionality
• Unique constraint: (translation, lang, book, chapter, verse)
• Indexes: on (book, chapter), testament

User Content Models

Bookmark (Verse-level)

• Fields: id, userId, verseId, note, color (#FFD700 default), createdAt
• Unique constraint: (userId, verseId) - one bookmark per verse per user
• Indexes: on userId

ChapterBookmark

• Fields: id, userId, bookId, chapterNum, note, createdAt
• Unique constraint: (userId, bookId, chapterNum)
• Index: on userId

Highlight

• Fields: id, userId, verseId, color, note (Text), tags[], createdAt, updatedAt
• Supports colored highlighting with notes and tags
• Unique constraint: (userId, verseId)
• Indexes: on userId, verseId

Note

• Fields: id, userId, verseId, content (Text), createdAt, updatedAt
• User notes on verses
• Indexes: on userId, verseId

ReadingHistory

• Fields: id, userId, versionId, bookId, chapterNum, verseNum, viewedAt
• Tracks user reading position
• Unique constraint: (userId, versionId) - one reading position per version per user
• Indexes: on (userId, viewedAt), (userId, versionId)

Communication Models

ChatConversation

• Fields: id, userId (optional for anonymous), title (auto-generated), language ("ro"/"en"), isActive, createdAt, updatedAt, lastMessageAt
• Supports authenticated and anonymous conversations
• Cascade delete on user delete
• Index: composite (userId, language, lastMessageAt)

ChatMessage

• Fields: id, conversationId, userId (optional), role (USER/ASSISTANT/SYSTEM), content (Text), metadata (JSON), timestamp
• Cascade delete on conversation/user delete
• Indexes: on (conversationId, timestamp), (userId, timestamp)

ChatMessageRole Enum

• Values: USER, ASSISTANT, SYSTEM

Prayer System Models

PrayerRequest

• Fields: id, userId (optional), title, description (Text), category (personal/family/health/work/ministry/world), author, isAnonymous, isPublic, language, prayerCount, isActive, createdAt, updatedAt
• Supports public/private and anonymous prayers
• Cascade delete on user delete
• Indexes: on createdAt, category, isActive

Prayer

• Fields: id, requestId, ipAddress, createdAt
• Anonymous prayer tracking via IP address
• Unique constraint: (requestId, ipAddress) - one prayer per IP per request

UserPrayer

• Fields: id, userId, requestId, createdAt
• Authenticated user prayer tracking
• Unique constraint: (userId, requestId)
• Indexes: on userId, requestId

Reading Plans Models

ReadingPlan

• Fields: id, name, description, type (PREDEFINED/CUSTOM), duration (days), schedule (JSON), difficulty, language, isActive, createdAt, updatedAt
• Flexible schedule format supporting multiple languages
• Indexes: on type, language, isActive

UserReadingPlan

• Fields: id, userId, planId (optional for custom), name, startDate, targetEndDate, actualEndDate, status (ACTIVE/COMPLETED/PAUSED/CANCELLED), currentDay, completedDays, streak, longestStreak, customSchedule (JSON), reminderEnabled, reminderTime, createdAt, updatedAt
• Tracks user progress in reading plans with streaks
• Indexes: on userId, status, (userId, status)

UserReadingProgress

• Fields: id, userId, userPlanId, planDay, date, bookId, chapterNum, versesRead, completed, notes (Text), createdAt, updatedAt
• Unique constraint: (userPlanId, planDay, bookId, chapterNum) - one entry per chapter per day per plan
• Indexes: on userId, userPlanId, (userId, date)

Payment & Subscription Models

Donation

• Fields: id, userId (optional), stripeSessionId (unique), stripePaymentId, email, name, amount (cents), currency ("usd" default), status (PENDING/COMPLETED/FAILED/REFUNDED/CANCELLED), message (Text), isAnonymous, isRecurring, recurringInterval, metadata (JSON), createdAt, updatedAt
• Supports one-time and recurring donations
• Set null on user delete (anonymous donations preserved)
• Indexes: on userId, status, createdAt, email

Subscription

• Fields: id, userId, stripeSubscriptionId (unique), stripePriceId, stripeCustomerId, status (SubscriptionStatus enum), currentPeriodStart, currentPeriodEnd, cancelAtPeriodEnd, tier ("premium"), interval ("month"/"year"), metadata (JSON), createdAt, updatedAt
• Tracks active Stripe subscriptions
• Cascade delete on user delete
• Indexes: on userId, status, stripeSubscriptionId

SubscriptionStatus Enum

• Values: ACTIVE, CANCELLED, PAST_DUE, TRIALING, INCOMPLETE, INCOMPLETE_EXPIRED, UNPAID

Content Management Models

Page

• Fields: id, title, slug (unique), content (Text), contentType (RICH_TEXT/HTML/MARKDOWN), excerpt, featuredImage, seoTitle, seoDescription, status (DRAFT/PUBLISHED/ARCHIVED), showInNavigation, showInFooter, navigationOrder, footerOrder, createdBy, updatedBy, createdAt, updatedAt, publishedAt
• Full CMS functionality with SEO support
• Indexes: on slug, status, (showInNavigation, navigationOrder), (showInFooter, footerOrder)

MediaFile

• Fields: id, filename, originalName, mimeType, size, path, url, alt, uploadedBy, createdAt
• File storage tracking
• Indexes: on uploadedBy, mimeType

SocialMediaLink

• Fields: id, platform (unique), name, url, icon, isEnabled, order, createdBy, updatedBy, createdAt, updatedAt
• Manages social media links in footer
• Index: on (isEnabled, order)

MailgunSettings

• Fields: id, apiKey (encrypted), domain, region ("US"/"EU"), fromEmail, fromName, replyToEmail, isEnabled, testMode, webhookUrl, updatedBy, createdAt, updatedAt
• Email service configuration
• Index: on isEnabled

User Preferences

UserPreference

• Fields: id, userId, key, value
• Key-value store for user settings
• Unique constraint: (userId, key)

---

2. AUTHENTICATION SYSTEM

JWT-Based Authentication

Token Architecture

• Algorithm: JWT with HS256
• Secret: Stored in JWT_SECRET environment variable
• Expiration: 7 days for user tokens, 24 hours for admin tokens
• Payload: { userId: string } for users, { userId, email, role, type: 'admin' } for admins

Authentication Flow

1. User Registration (POST /api/auth/register)

   • Validates email/password with Zod schemas
   • Creates User with hashed password (bcryptjs, 10 rounds)
   • Generates JWT token
   • Creates Session record with 7-day expiration
   • Returns user data and token

2. User Login (POST /api/auth/login)

   • Validates credentials against stored hash
   • Generates JWT token
   • Creates Session record
   • Updates lastLoginAt
   • Returns user data and token

3. Token Verification

   • verifyToken(token): Verifies JWT signature and returns decoded payload
   • getUserFromToken(token): Retrieves full user record from token
   • isTokenExpired(token): Checks expiration without verification (client-side safe)

4. Admin Authentication (POST /api/admin/auth/login)

   • Requires role to be "admin" or "moderator"
   • Returns admin token via secure httpOnly cookie
   • Cookie: adminToken, httpOnly, secure (production), sameSite: strict, max age 8 hours
   • Also accepts Bearer token in Authorization header

Admin Permission System

Admin Roles

• Admin: Full system access (super admin)
• Moderator: Limited access (content, user management, analytics)

Permission Enums (from lib/admin-auth.ts)

READ_USERS
WRITE_USERS
DELETE_USERS
READ_CONTENT
WRITE_CONTENT
DELETE_CONTENT
READ_ANALYTICS
READ_CHAT
WRITE_CHAT
DELETE_CHAT
SYSTEM_BACKUP
SYSTEM_HEALTH
SUPER_ADMIN

Moderator Permissions: READ_USERS, WRITE_USERS, READ_CONTENT, WRITE_CONTENT, DELETE_CONTENT, READ_ANALYTICS, READ_CHAT, WRITE_CHAT

Auth Middleware

• verifyAdminAuth(): Checks Bearer token or adminToken cookie
• hasAdminAccess(): Validates admin/moderator role
• isSuperAdmin(): Checks admin role specifically
• hasPermission(): Validates specific permission

Client-Side Auth Management

Token Handling

• Tokens stored in localStorage as authToken
• Client function: isTokenExpired() - decodes JWT without verification
• Client function: clearExpiredToken() - removes expired tokens from storage

Authentication Headers

• Format: Authorization: Bearer <token>
• Used in all protected API endpoints

---

3. PAYMENT & SUBSCRIPTION SYSTEM

Stripe Integration

Configuration

• Client Library: @stripe/stripe-js 8.0.0
• Server Library: stripe 19.1.0
• API Version: 2025-09-30.clover
• Keys:
  • Public Key: NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
  • Secret Key: STRIPE_SECRET_KEY
  • Webhook Secret: STRIPE_WEBHOOK_SECRET

Subscription Pricing

• Free Tier: 10 conversations/month limit
• Premium Tier: Unlimited conversations
• Price IDs:
  • STRIPE_PREMIUM_MONTHLY_PRICE_ID
  • STRIPE_PREMIUM_YEARLY_PRICE_ID

Donation System

Donation Flow (POST /api/stripe/checkout)

• Creates Stripe checkout session
• Supports one-time and recurring donations
• Presets: $5, $10, $25, $50, $100, $250
• Tracks via Donation model with statuses:
  • PENDING (initial)
  • COMPLETED (payment succeeded)
  • FAILED (payment failed)
  • REFUNDED (refunded)
  • CANCELLED (session expired)

Donation Webhooks (POST /api/stripe/webhook)

• checkout.session.completed: Updates donation to COMPLETED
• checkout.session.expired: Updates donation to CANCELLED
• payment_intent.payment_failed: Updates donation to FAILED
• charge.refunded: Updates donation to REFUNDED
• Stores payment metadata (status, email, error info)

Subscription System

Subscription Flow (POST /api/subscriptions/checkout)

• Creates Stripe customer if not exists
• Creates subscription checkout session
• Validates price ID configuration
• Prevents duplicate active subscriptions
• Returns session ID and checkout URL
• Allows promotion codes
• Requires Bearer token authentication

Subscription Portal (POST /api/subscriptions/portal)

• Generates Stripe customer portal link
• Users can manage/cancel subscriptions
• Requires authentication

Subscription Webhooks (POST /api/stripe/webhook)

• customer.subscription.created: Creates Subscription record, updates user tier to premium
• customer.subscription.updated: Updates Subscription and user tier/limit
• customer.subscription.deleted: Downgrades user to free tier
• invoice.payment_succeeded: Ensures subscription marked active
• invoice.payment_failed: Sets subscription status to past_due

Webhook Payload Handling

• Verifies Stripe signature
• Extracts userId from subscription metadata
• Extracts pricing tier and interval from price ID
• Updates both Subscription and User models atomically

Conversation Limit Management

Limit Checking (checkConversationLimit())

• Validates user subscription tier and count
• Resets monthly counter if period expired
• Premium users with active subscriptions get unlimited access
• Free users get 10/month limit
• Automatic monthly reset calculation

Limit Enforcement

• Checked before creating new conversation
• Returns: { allowed, remaining, limit, tier, resetDate }
• Returns infinite remaining for premium users

Limit Increment (incrementConversationCount())

• Called when new conversation created
• Sets initial reset date if not set (1 month from now)
• Increments counter by 1

---

4. API STRUCTURE & ENDPOINTS

Framework & Runtime

• Framework: Next.js 15.5.3 with App Router
• Runtime: All routes set to nodejs (not Edge)
• Response Format: JSON via NextResponse

API Categories

Authentication Endpoints

User Auth

• POST /api/auth/register - User registration with email/password
• POST /api/auth/login - User login
• GET /api/auth/me - Get authenticated user profile
• POST /api/auth/logout - Logout (clear token)

Admin Auth

• POST /api/admin/auth/login - Admin login with role validation
• GET /api/admin/auth/me - Get admin profile
• POST /api/admin/auth/logout - Admin logout

Bible Data Endpoints

Bible Versions

• GET /api/bible/versions - List Bible versions by language
• Query params: locale, all, limit, search
• Caching: 1 hour cache with 2-hour stale-while-revalidate

Bible Books

• GET /api/bible/books - Get books for a version

Bible Chapters

• GET /api/bible/chapter - Get full chapter with verses

Bible Verses

• GET /api/bible/verses - Get specific verses
• GET /api/bible/search - Search verses

SEO URLs

• GET /api/bible/seo-url - Convert friendly URLs to references

User Content Endpoints

Bookmarks

• GET /api/bookmarks/all - Get all user bookmarks (verses & chapters)
• POST /api/bookmarks/verse - Create verse bookmark
• GET /api/bookmarks/verse/check - Check if verse bookmarked
• POST /api/bookmarks/verse/bulk-check - Check multiple verses
• POST /api/bookmarks/chapter - Create chapter bookmark
• GET /api/bookmarks/chapter/check - Check if chapter bookmarked

Highlights

• GET /api/highlights - Get user highlights
• POST /api/highlights - Create highlight with color/tags/notes
• PUT /api/highlights/[id] - Update highlight
• DELETE /api/highlights/[id] - Delete highlight
• POST /api/highlights/bulk - Bulk operations

Notes

• Not shown in list but available through verse endpoints

User Management Endpoints

Profile

• GET /api/user/profile - Get user profile
• PUT /api/user/profile - Update profile

Settings

• GET /api/user/settings - Get user settings
• PUT /api/user/settings - Update settings

Favorite Version

• PUT /api/user/favorite-version - Set default Bible version

Reading Progress

• GET /api/user/reading-progress - Get reading position
• PUT /api/user/reading-progress - Update reading position

Reading Plans Endpoints

Reading Plans

• GET /api/reading-plans - List all available plans

User Reading Plans

• GET /api/user/reading-plans - Get user's reading plans with status filter
• POST /api/user/reading-plans - Enroll in plan or create custom plan
• GET /api/user/reading-plans/[id] - Get specific plan details
• PUT /api/user/reading-plans/[id] - Update plan
• DELETE /api/user/reading-plans/[id] - Cancel plan

Reading Progress

• GET /api/user/reading-plans/[id]/progress - Get progress for plan
• POST /api/user/reading-plans/[id]/progress - Log reading for day
• PUT /api/user/reading-plans/[id]/progress - Update progress

Prayer Endpoints

Prayer Requests

• GET /api/prayers - List public prayer requests (with filters)
  • Query params: category, limit, visibility, languages
  • Supports public/private filtering based on auth
• POST /api/prayers - Create prayer request
  • Supports anonymous or authenticated
• GET /api/prayers/[id] - Get prayer details
• POST /api/prayers/[id]/pray - Log prayer for request
• PUT /api/prayers/[id] - Update prayer (owner only)
• DELETE /api/prayers/[id] - Delete prayer (owner only)

Prayer Generation

• POST /api/prayers/generate - Generate prayer prompt (AI)

Chat Endpoints

Chat Conversations

• GET /api/chat/conversations - List user conversations (auth required)
• POST /api/chat/conversations - Create new conversation
• GET /api/chat/conversations/[id] - Get conversation with messages
• PUT /api/chat/conversations/[id] - Update conversation
• DELETE /api/chat/conversations/[id] - Delete conversation

Chat Messages

• POST /api/chat - Send message and get AI response
  • Status: Currently disabled (returns 503)
  • Requires Bearer token auth for new conversations
  • Checks conversation limits for free users
  • Integrates with Azure OpenAI
  • Stores messages in database for authenticated users
  • Uses vector search for relevant Bible verses

Subscription & Payment Endpoints

Donations

• POST /api/stripe/checkout - Create donation checkout session

Subscriptions

• POST /api/subscriptions/checkout - Create subscription checkout session
• POST /api/subscriptions/portal - Get customer portal URL

Webhooks

• POST /api/stripe/webhook - Stripe webhook handler

Admin Endpoints

Users

• GET /api/admin/users - List users with pagination/filtering
  • Query params: page, pageSize, search, role
  • Returns user counts (conversations, prayers, bookmarks)
• GET /api/admin/users/[id] - Get user details
• PUT /api/admin/users/[id] - Update user
• DELETE /api/admin/users/[id] - Delete user

Chat Management

• GET /api/admin/chat/conversations - List all conversations
• GET /api/admin/chat/conversations/[id] - Get conversation details
• DELETE /api/admin/chat/conversations/[id] - Delete conversation

Content Management

• GET /api/admin/pages - List CMS pages
• POST /api/admin/pages - Create page
• GET /api/admin/pages/[id] - Get page
• PUT /api/admin/pages/[id] - Update page
• DELETE /api/admin/pages/[id] - Delete page

Prayer Requests

• GET /api/admin/content/prayer-requests - List all prayers
• GET /api/admin/content/prayer-requests/[id] - Get prayer details
• PUT /api/admin/content/prayer-requests/[id] - Update prayer
• DELETE /api/admin/content/prayer-requests/[id] - Delete prayer

Media Management

• POST /api/admin/media - Upload media files
• DELETE /api/admin/media/[id] - Delete media

Social Media

• GET /api/admin/social-media - List social links
• POST /api/admin/social-media - Create social link
• PUT /api/admin/social-media/[id] - Update social link
• DELETE /api/admin/social-media/[id] - Delete social link

Email Configuration

• GET /api/admin/mailgun - Get Mailgun settings
• PUT /api/admin/mailgun - Update Mailgun settings
• POST /api/admin/mailgun/test - Test email connection

Analytics Endpoints

Overview

• GET /api/admin/analytics/overview - Comprehensive dashboard stats
  • Period-based stats (default 30 days)
  • User metrics: total, new, active
  • Content metrics: prayers, requests, conversations
  • Category distributions
  • Daily activity breakdown

Content Analytics

• GET /api/admin/analytics/content - Content-specific metrics

User Analytics

• GET /api/admin/analytics/users - User behavior metrics

Real-time Analytics

• GET /api/admin/analytics/realtime - Current active users/activity

Stats

• GET /api/stats - Public statistics

System Endpoints

Health Check

• GET /api/health - API health status

System Health

• GET /api/admin/system/health - Detailed system health

System Backup

• POST /api/admin/system/backup - Database backup

Utility Endpoints

Contact Form

• POST /api/contact - Contact form submission

CAPTCHA

• POST /api/captcha - CAPTCHA verification

Debug Endpoints (Development)

• GET /api/debug/user - Debug user info
• GET /api/debug/schema - Debug schema info
• GET /api/debug/token - Debug token info

---

5. KEY BUSINESS LOGIC & FEATURES

Conversation Limit System

• Free tier: 10 conversations/month
• Premium tier: Unlimited
• Automatic monthly reset
• Prevents over-usage

Prayer System Features

• Public/private prayers
• Anonymous submission support
• Prayer count tracking (IP-based for anonymous, user-based for authenticated)
• Category classification (personal, family, health, work, ministry, world)
• Language-aware filtering
• Multi-language support

Reading Plans

• Predefined and custom plans
• Daily tracking with streak system
• Progress tracking with completion status
• Reminder system (enabled/disabled with time)
• Flexible JSON-based schedules
• Target date management

Chat System (Currently Disabled)

• Conversation persistence
• Message history tracking
• Integration with Azure OpenAI
• Vector search for Bible verses
• Context-aware responses
• Multi-language system prompts
• Subscription-based limit enforcement

Vector Search (BiblePassage model)

• Embedding-based verse search
• Language-specific filtering
• Used for AI chat context
• Supports: EN (ASV), ES (RVA 1909), etc.

Admin System Features

• User management with pagination
• Chat conversation moderation
• Content (pages) management with SEO
• Prayer request moderation
• Media file management
• Social media link management
• Email service configuration (Mailgun)
• Comprehensive analytics dashboard
• Daily activity tracking
• System health monitoring

---

6. EXTERNAL INTEGRATIONS

Stripe

• Payment processing (one-time)
• Subscription management (recurring)
• Webhook event handling
• Customer portal access

Azure OpenAI

• Chat completions API
• Multi-language support
• Temperature/top_p configuration
• Content filtering detection
• Fallback responses

Mailgun

• Email service
• Contact form handling
• Password reset emails
• Test mode support
• Multi-region support (US/EU)

Vector Database

• PostgreSQL with pgvector extension
• Bible verse embeddings
• Hybrid search capability

---

7. FILE STORAGE

System

• Model: MediaFile
• Fields: filename, originalName, mimeType, size, path, url, alt, uploadedBy
• Tracking: User upload attribution, creation timestamp
• Indexes: By uploader, by MIME type

Upload Endpoint

• POST /api/admin/media - Admin only file uploads

Usage in CMS

• Pages can have featured images
• Supported in content rich text editor

---

8. TECHNOLOGY STACK

Backend Framework

• Next.js 15.5.3 (with App Router)
• Node.js runtime

Database

• PostgreSQL
• Prisma ORM 6.16.2
• pgvector for embeddings

Authentication & Security

• JWT (jsonwebtoken 9.0.2)
• bcryptjs for password hashing (3.0.2)
• CORS headers management

API Integration

• Stripe 19.1.0 (payments)
• Mailgun.js 12.0.3 (email)
• OpenAI 5.22.0 (Azure OpenAI)
• Socket.io 4.8.1 (WebSocket support)

Validation

• Zod 3.25.76 (schema validation)

State Management

• Zustand 5.0.8

Utilities

• uuid 13.0.0 (ID generation)
• axios (via stripe, mailgun, openai)

Development

• TypeScript 5.9.2
• tsx 4.20.5 (TypeScript runner)

---

9. ENVIRONMENT VARIABLES

Database

• DATABASE_URL - PostgreSQL connection string
• VECTOR_SCHEMA - Schema name for vector tables (default: ai_bible)
• EMBED_DIMS - Embedding dimensions (default: 1536)

JWT & Auth

• JWT_SECRET - Secret key for JWT signing

Stripe

• NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY - Public key (client-side)
• STRIPE_SECRET_KEY - Secret key (server-side)
• STRIPE_WEBHOOK_SECRET - Webhook signature verification
• STRIPE_PREMIUM_MONTHLY_PRICE_ID - Monthly subscription price ID
• STRIPE_PREMIUM_YEARLY_PRICE_ID - Yearly subscription price ID

Azure OpenAI

• AZURE_OPENAI_ENDPOINT - API endpoint
• AZURE_OPENAI_KEY - API key
• AZURE_OPENAI_DEPLOYMENT - Model deployment name
• AZURE_OPENAI_API_VERSION - API version

Email (Mailgun)

• Configured in database MailgunSettings table (encrypted in DB)
• Can be updated via admin panel

Application

• NEXTAUTH_URL - Base URL for callbacks
• NODE_ENV - Environment (development/production)

---

10. CURRENT STATUS & NOTES

Disabled Features

• Chat feature currently disabled (returns 503 Service Unavailable)
• Reason: Likely maintenance or missing Azure OpenAI configuration

Pending Implementation

• Password reset functionality (structure in place, not fully implemented)
• WebSocket support (server available but not actively used)

Security Considerations

• Mailgun API keys stored encrypted in database
• JWT secrets required for all environments
• Admin tokens use httpOnly cookies for CSRF protection
• Stripe webhook signature verification implemented
• User data cascades deleted appropriately

Performance Optimizations

• Database indexes on frequently queried fields
• Composite indexes for common filter combinations
• Unique constraints to prevent duplicates
• Pagination in admin list endpoints
• Select-only fields to reduce data transfer

Monitoring & Logging

• Extensive console logging throughout API routes
• Error tracking in webhook handlers
• Analytics dashboard for monitoring usage patterns

---

11. DATA RELATIONSHIPS DIAGRAM

User (1)
├── (1:M) Session
├── (1:M) ChatConversation -> (1:M) ChatMessage
├── (1:M) Bookmark -> BibleVerse -> BibleChapter -> BibleBook -> BibleVersion
├── (1:M) ChapterBookmark -> BibleBook
├── (1:M) Highlight -> BibleVerse
├── (1:M) Note -> BibleVerse
├── (1:M) ReadingHistory -> BibleVersion
├── (1:M) PrayerRequest -> (1:M) Prayer & UserPrayer
├── (1:M) UserReadingPlan -> ReadingPlan & UserReadingProgress
├── (1:M) Donation
├── (1:M) Subscription
├── (1:M) Page (created & updated)
├── (1:M) MediaFile
├── (1:M) SocialMediaLink (created & updated)
└── (1:M) MailgunSettings (updated)

---

12. API RESPONSE PATTERNS

Success Response

{
  "success": true,
  "data": {},
  "message": "Optional message"
}

Error Response

{
  "success": false,
  "error": "Error message",
  "details": [] // Optional validation details
}

Pagination Response

{
  "data": [],
  "pagination": {
    "page": 0,
    "pageSize": 10,
    "total": 100,
    "totalPages": 10
  }
}

---

13. DEPLOYMENT CONSIDERATIONS

Build Configuration

• NODE_OPTIONS='--max-old-space-size=4096' for standard builds
• NODE_OPTIONS='--max-old-space-size=8192' for production builds
• NEXT_PRIVATE_SKIP_SIZE_LIMIT=1 available for fast builds (skips size check)

Production Checklist

• All environment variables configured
• Database migrations applied (prisma migrate deploy)
• Stripe webhooks configured with correct URL
• Azure OpenAI credentials validated
• Mailgun settings configured and tested
• CORS headers for cross-origin requests
• HTTPS enforced for secure cookies
• Database backups enabled
• Monitoring/alerting configured

---

Conclusion

The Biblical Guide backend is a sophisticated, well-structured application with:

• Comprehensive user management and authentication
• Flexible subscription/payment system via Stripe
• Rich content management for Bible data
• Multi-feature user engagement (bookmarks, notes, highlights, prayers, reading plans)
• Full admin panel for system management
• AI-powered chat with context awareness
• Scalable architecture with proper indexing and data relationships

The codebase demonstrates good practices in API design, security, and data modeling with room for future enhancements in performance optimization and additional features.