build: production build with Phase 1 2025 Bible Reader implementation complete

Includes all Phase 1 features: - Search-first navigation with auto-complete - Responsive reading interface (desktop/tablet/mobile) - 4 customization presets + full fine-tuning controls - Layered details panel with notes, bookmarks, highlights - Smart offline caching with IndexedDB and auto-sync - Full accessibility (WCAG 2.1 AA) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-11 20:38:01 +00:00
parent b8652b9f0a
commit 9b5c0ed8bb
50 changed files with 20146 additions and 859 deletions
--- a/BACKEND_DOCUMENTATION_INDEX.md
+++ b/BACKEND_DOCUMENTATION_INDEX.md
@@ -0,0 +1,350 @@
+# 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
+
+```bash
+# 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/`.