docs: add Phase 2.1B deployment plan

docs/DEPLOYMENT_PLAN_2_1B.md

@@ -0,0 +1,253 @@
+# Phase 2.1B Deployment Plan
+
+**Date:** 2025-01-12
+**Target Environment:** Production
+**Deployment Strategy:** Rolling update with health checks
+**Estimated Downtime:** < 2 minutes
+
+---
+
+## Pre-Deployment Checklist
+
+### Code Quality ✅
+- [x] All tests passing (42/42)
+- [x] No TypeScript errors
+- [x] No build warnings
+- [x] All commits signed and documented
+- [x] Code reviewed and tested
+
+### Database ✅
+- [x] Migration created: `add_highlights`
+- [x] UserHighlight schema finalized
+- [x] Unique constraints in place
+- [x] Indexes optimized
+- [x] No breaking changes to existing schema
+
+### API Endpoints ✅
+- [x] POST /api/highlights (single create)
+- [x] POST /api/highlights/bulk (batch sync)
+- [x] GET /api/highlights/all (pull sync)
+- [x] GET /api/bible/cross-references (placeholder)
+- [x] All endpoints authenticated with Clerk
+- [x] All endpoints have error handling
+
+### Frontend ✅
+- [x] IndexedDB storage working
+- [x] Sync manager functional
+- [x] UI components rendering
+- [x] Status indicators working
+- [x] Conflict resolution tested
+- [x] E2E tests passing
+
+### Documentation ✅
+- [x] Implementation plan complete
+- [x] API documentation updated
+- [x] Database schema documented
+- [x] Architecture diagrams available
+- [x] Troubleshooting guide prepared
+
+---
+
+## Deployment Steps
+
+### Step 1: Code Preparation
+```bash
+# Ensure we're on master branch with all Phase 2.1B commits
+git branch -v
+git log --oneline -10
+
+# Verify working directory is clean
+git status
+
+# Should output: "nothing to commit, working tree clean"
+```
+
+### Step 2: Pre-Deployment Verification
+```bash
+# Run full test suite
+npm test 2>&1 | tail -20
+
+# Expected: All tests pass
+
+# Build production bundle
+npm run build:prod 2>&1 | tail -50
+
+# Expected: Build completes with no errors
+```
+
+### Step 3: Database Migration
+```bash
+# Before deployment, run database migration
+npm run db:migrate
+
+# Expected: Migration "add_highlights" applied successfully
+# This creates:
+# - UserHighlight table
+# - Unique constraint on [userId, verseId]
+# - Indexes on userId and verseId
+```
+
+### Step 4: Deploy to Production
+```bash
+# Option A: If using production branch
+git push origin master:production
+
+# Option B: Run deploy script (if on production server)
+./deploy.sh
+
+# Expected output:
+# - Code fetched from production branch
+# - Dependencies installed
+# - Application built
+# - PM2 restart successful
+# - Health check passes
+# - Application running on port 3010
+```
+
+### Step 5: Post-Deployment Verification
+```bash
+# Check application health
+curl http://localhost:3010/api/health
+
+# Expected: 200 OK response
+
+# Check API endpoints
+curl -H "Authorization: Bearer $TOKEN" http://localhost:3010/api/highlights/all
+
+# Expected: 401 (if no token) or 200 with highlights array
+```
+
+### Step 6: Monitor
+```bash
+# Monitor PM2 logs
+pm2 logs ghidul-biblic
+
+# Check application status
+pm2 status
+
+# Expected: App status "online"
+```
+
+---
+
+## Rollback Plan
+
+### If Issues Occur
+
+```bash
+# 1. Immediate rollback
+git reset --hard origin/master~19  # Before Phase 2.1B commits
+
+# 2. Rebuild and restart
+npm run build:prod
+pm2 restart ghidul-biblic
+
+# 3. Database rollback (if needed)
+# - Downgrade migration: npx prisma migrate resolve --rolled-back <migration_id>
+# - Or keep highlights table (non-breaking change, data preserved)
+
+# 4. Monitor recovery
+pm2 logs ghidul-biblic
+curl http://localhost:3010/api/health
+```
+
+---
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|-----------|
+| Build failure | Low | High | Pre-tested, all tests pass |
+| Migration failure | Low | High | Migration tested locally |
+| API errors | Low | Medium | Comprehensive error handling |
+| Performance degradation | Low | Medium | Sync optimized (30s polling) |
+| Data loss | Very Low | Critical | Database constraints in place |
+
+---
+
+## Deployment Commands
+
+```bash
+# Complete automated deployment flow
+git fetch origin
+git checkout production
+git reset --hard origin/master  # Pull Phase 2.1B commits
+npm ci
+npm run db:migrate
+npm run build:prod
+pm2 restart ghidul-biblic
+sleep 5
+curl http://localhost:3010/api/health
+pm2 logs ghidul-biblic --lines 20
+```
+
+---
+
+## Success Criteria
+
+✅ Application builds without errors
+✅ All tests pass (42/42)
+✅ Database migration succeeds
+✅ Health check passes
+✅ API endpoints respond
+✅ UI loads without console errors
+✅ Highlights can be created locally
+✅ Sync to backend works
+✅ Conflict resolution works
+✅ Status indicators display correctly
+
+---
+
+## Post-Deployment Tasks
+
+1. **Monitor for 1 hour**
+   - Watch PM2 logs for errors
+   - Check error tracking system
+   - Monitor performance metrics
+
+2. **User Communication** (optional)
+   - Announce new highlight sync feature
+   - Point users to documentation
+   - Gather feedback
+
+3. **Analytics**
+   - Track highlight sync success rate
+   - Monitor API response times
+   - Track error rates
+
+4. **Documentation**
+   - Update user guides
+   - Add troubleshooting section
+   - Document known issues
+
+---
+
+## Commits Ready for Deployment
+
+```
+28bdd37 docs: add Phase 2.1B completion report
+cecccd1 build: complete Phase 2.1B backend sync integration
+180da44 test: add E2E tests for highlights sync flow
+97f8aa5 feat: integrate sync status indicator into highlights panel
+c50cf86 feat: create sync status indicator component
+3e3e90f feat: add pull sync on login with conflict resolution
+73171b5 feat: implement client-side sync with bulk API
+82c537d feat: implement sync conflict resolver with timestamp-based merging
+afaf580 build: complete Phase 2.1 implementation and verify build
+b7b18c8 feat: add UserHighlight model to database schema
+7ca2076 feat: add backend API endpoints for highlights and cross-references
+```
+
+**Total: 19 commits** (Phase 2.1 + 2.1B combined)
+
+---
+
+## Deployment Status
+
+**Ready for Production:** ✅ YES
+**Approved for Deployment:** ⏳ PENDING
+**Deployment Date:** 2025-01-12
+**Deployed By:** [To be filled]
+**Deployment Result:** [To be filled]
+
+---