biblical-guide.com/BACKEND_DOCUMENTATION_INDEX.md

Backend Documentation Index

Overview

This directory contains comprehensive documentation of the Biblical Guide backend architecture. The analysis covers the complete backend system including database design, authentication, APIs, payment processing, and admin functionality.

Documentation Files

1. BACKEND_ARCHITECTURE_ANALYSIS.md (Primary Document)

Size: 29 KB | Lines: 890 | Sections: 13

Complete architectural documentation covering:

• Section 1: Database Schema (32 models)

  • User Management
  • Bible Data Models
  • User Content Models
  • Communication Models
  • Prayer System Models
  • Reading Plans Models
  • Payment & Subscription Models
  • Content Management Models
  • User Preferences

• Section 2: Authentication System

  • JWT Token Architecture
  • User Registration/Login Flow
  • Admin Authentication
  • Permission System
  • Client-Side Auth Management

• Section 3: Payment & Subscription System

  • Stripe Configuration
  • Donation Flow
  • Subscription Flow
  • Webhook Handling
  • Conversation Limit Management

• Section 4: API Structure & Endpoints

  • Framework & Runtime
  • 12 API Categories
  • 70+ Documented Endpoints
  • Request/Response Patterns

• Section 5: Key Business Logic

  • Conversation Limit System
  • Prayer System Features
  • Reading Plans
  • Chat System
  • Vector Search
  • Admin Features

• Section 6-13: Additional Topics

  • External Integrations
  • File Storage
  • Technology Stack
  • Environment Variables
  • Current Status & Notes
  • Data Relationships
  • API Response Patterns
  • Deployment Considerations

Best For: Comprehensive understanding, onboarding new developers, system design decisions

---

2. BACKEND_QUICK_REFERENCE.md (Quick Lookup)

Size: 9.2 KB | Lines: 353 | Sections: 14

Quick reference guide for common tasks:

• Model Index: 32 models organized by category
• Authentication Table: Endpoints, methods, auth requirements
• API Endpoints: Organized by category with example URLs
• Subscription Tiers: Feature comparison table
• Data Constraints: Unique constraints and cascades
• Webhook Events: Stripe events and their effects
• Admin Permissions: Role-based access matrix
• Limits & Defaults: Important configuration values
• Query Patterns: Common Prisma queries
• Environment Checklist: Required variables
• Development Tasks: Common npm scripts
• Performance Tips: Optimization guidelines
• Troubleshooting: Common issues and solutions
• Resource Links: External documentation

Best For: Day-to-day reference, quick lookups, during development

---

Key Information at a Glance

Technology Stack

Component	Technology	Version
Framework	Next.js	15.5.3
Database	PostgreSQL	Latest
ORM	Prisma	6.16.2
Auth	JWT	via jsonwebtoken 9.0.2
Payments	Stripe	19.1.0
Email	Mailgun	12.0.3
AI	Azure OpenAI	Custom
Validation	Zod	3.25.76

Database Statistics

• Total Models: 32
• Total Indexes: 25+
• Unique Constraints: 20+
• Foreign Key Cascades: 8
• Text Fields: 15+ (for long content)
• JSON Fields: 5 (for flexible data)

API Statistics

• Total Endpoints: 70+
• Public Endpoints: 15
• Protected Endpoints: 40
• Admin Endpoints: 25+
• Webhook Endpoints: 2
• Categories: 12

Authentication

• User Token Expiry: 7 days
• Admin Token Expiry: 24 hours (8 hours for cookie)
• Password Hash Rounds: 10 (bcryptjs)
• Session Expiry: 7 days
• Admin Roles: Admin, Moderator
• Permission Types: 13

Subscription System

• Free Tier Limit: 10 conversations/month
• Premium Tier Limit: Unlimited
• Webhook Events Handled: 9+
• Payment Methods: Stripe (card)
• Donation Presets: $5, $10, $25, $50, $100, $250

Quick Start References

Common Tasks

Find Information About:

• Specific API endpoint → Search "API STRUCTURE" in ARCHITECTURE_ANALYSIS.md or check QUICK_REFERENCE.md
• Database model → "DATABASE SCHEMA" in ARCHITECTURE_ANALYSIS.md or MODEL quick index
• Authentication → "AUTHENTICATION SYSTEM" section
• Payment flow → "PAYMENT & SUBSCRIPTION SYSTEM" section
• Admin panel → "ADMIN ENDPOINTS" in QUICK_REFERENCE.md

For Development:

• Set up environment → QUICK_REFERENCE.md "Environment Setup Checklist"
• Common database queries → QUICK_REFERENCE.md "Common Query Patterns"
• API testing → Check each endpoint in ARCHITECTURE_ANALYSIS.md Section 4
• Troubleshooting → QUICK_REFERENCE.md "Troubleshooting" section

For Deployment:

• Production checklist → ARCHITECTURE_ANALYSIS.md Section 13
• Environment variables → ARCHITECTURE_ANALYSIS.md Section 9
• Migrations → QUICK_REFERENCE.md "Common Development Tasks"
• Monitoring → ARCHITECTURE_ANALYSIS.md "Monitoring & Logging"

Data Models by Feature

Bible Reading

• BibleVersion, BibleBook, BibleChapter, BibleVerse
• BiblePassage (with embeddings)
• ReadingHistory

User Content

• Bookmark, ChapterBookmark
• Highlight, Note
• ReadingHistory

User Engagement

• PrayerRequest, Prayer, UserPrayer
• ReadingPlan, UserReadingPlan, UserReadingProgress
• ChatConversation, ChatMessage

Monetization

• Subscription, Donation
• User (subscription fields)

Administration

• Page, MediaFile
• SocialMediaLink, MailgunSettings

Security Features

Authentication

• JWT-based token authentication
• bcryptjs password hashing (10 rounds)
• Session tracking in database
• HttpOnly cookies for admin tokens
• CSRF protection via SameSite

Authorization

• Role-based access control (User/Admin/Moderator)
• Fine-grained permissions (13 types)
• Per-endpoint permission checks
• Cascade deletion on user removal

Data Protection

• Encrypted Mailgun API keys in database
• Stripe webhook signature verification
• Secure token generation (UUID)
• Proper SQL parameter binding via Prisma

Performance Optimizations

Database

• Strategic indexing on frequently queried fields
• Composite indexes for complex queries
• Unique constraints prevent duplicates
• Select-only queries reduce data transfer
• Proper relationship handling with include

API

• Bible version caching (1 hour + 2hr stale-while-revalidate)
• Pagination for list endpoints
• Selective field selection
• Connection pooling via Prisma

Frontend

• JWT stored in localStorage
• Client-side token expiration check
• Lazy loading of relationships

Disabled Features

Chat Feature (Currently Disabled)

• Endpoint: POST /api/chat
• Status: Returns 503 Service Unavailable
• Reason: Azure OpenAI configuration needed
• Features Blocked:
  • AI responses
  • Vector search for Bible verses
  • Conversation persistence
  • Limit enforcement

Password Reset

• Structure in place but incomplete
• Mailgun integration available
• Email template defined

Integration Points

External Services

1. Stripe - Payments, subscriptions, webhooks
2. Azure OpenAI - AI chat responses
3. Mailgun - Email delivery
4. PostgreSQL - Data persistence
5. pgvector - Vector embeddings (optional)

Internal Services

1. JWT - Token generation/verification
2. bcryptjs - Password hashing
3. Zod - Input validation
4. Prisma - Database ORM

Contribution Guidelines

When modifying the backend:

1. Database Changes

   • Update schema.prisma
   • Create migration: npx prisma migrate dev
   • Update BACKEND_ARCHITECTURE_ANALYSIS.md

2. API Changes

   • Follow existing patterns in /app/api
   • Use Zod schemas for validation
   • Add error handling with NextResponse
   • Update BACKEND_QUICK_REFERENCE.md endpoint list

3. Authentication Changes

   • Update lib/auth/* files
   • Verify JWT payload structure
   • Test with client-side auth management
   • Update ARCHITECTURE_ANALYSIS.md Section 2

4. Payment Changes

   • Update lib/stripe-server.ts or lib/subscription-utils.ts
   • Add/update webhook handlers
   • Update ARCHITECTURE_ANALYSIS.md Section 3
   • Test with Stripe test keys

Related Documents

In This Directory

• BACKEND_ARCHITECTURE_ANALYSIS.md (this document)
• BACKEND_QUICK_REFERENCE.md
• BACKEND_DOCUMENTATION_INDEX.md (this file)

In Repository Root

• README.md (project overview)
• package.json (dependencies)
• .env.example (environment template)

Prisma Files

• prisma/schema.prisma (database schema)
• prisma/migrations/* (migration history)

Useful Commands

# Database
npx prisma migrate deploy      # Apply migrations
npx prisma generate            # Generate Prisma client
npx prisma studio              # Open database UI

# Development
npm run dev                     # Start dev server
npm run build                   # Build for production
npm run import-bible            # Import Bible data

# Analysis
grep -r "export async function" app/api/  # Find all endpoints
grep -r "model " prisma/schema.prisma    # List all models

Support & Questions

For Understanding

1. Read BACKEND_QUICK_REFERENCE.md first (faster)
2. Dive into BACKEND_ARCHITECTURE_ANALYSIS.md for details
3. Check specific endpoint files in app/api/

For Debugging

1. Check QUICK_REFERENCE.md "Troubleshooting"
2. Enable logging: log: ['query', 'error'] in Prisma client
3. Use npx prisma studio to inspect data
4. Check API route logs and error messages

For Adding Features

1. Plan database changes in schema.prisma
2. Create API route in app/api/
3. Update documentation
4. Test with auth headers if needed
5. Configure webhooks if needed

Version History

Date	Changes	Version
2025-11-05	Initial comprehensive analysis	1.0

---

Last Updated: November 5, 2025 Document Version: 1.0 Backend Status: Production-ready (chat feature disabled)

For the latest information, always refer to the source files in /root/biblical-guide/.