biblical-guide.com/docs/DEPLOYMENT_PLAN_2_1B.md

# 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]

---