thrilltrack-explorer/migration/README.md

# ThrillWiki: Supabase → Django + React → Next.js 15 Migration Plan

## 📊 Current State
**Date:** January 2025  
**Django Backend:** ✅ 100% Complete  
**Frontend Framework:** React SPA (Vite) → Migrating to Next.js 15 + App Router + Turbopack  
**Frontend Services:** ❌ 5% Complete (only reports)  
**Frontend Integration:** ❌ 0% Complete (171 files using Supabase)  
**Package Manager:** Bun

## 🎯 Migration Goal
This is a **DUAL MIGRATION**:

1. **Backend Service Layer**: Replace ALL Supabase calls with Django REST API service layer
2. **Frontend Framework**: Convert React SPA to Next.js 15 + App Router + Turbopack

**Requirements:**
- ✅ 100% feature parity
- ✅ Sacred Pipeline protection (NEVER bypass moderation)
- ✅ Environment variables (NO hardcoded URLs/keys)
- ✅ Bun for package management
- ✅ All existing URLs preserved

## ⏱️ Total Estimated Time: 180-240 hours

---

## 📋 Phase Overview

| Phase | Name | Time | Priority | Status |
|-------|------|------|----------|--------|
| 1 | Foundation + Next.js Setup | 20-25h | CRITICAL | ⬜ Not Started |
| 2 | Authentication | 18-22h | CRITICAL | ⬜ Not Started |
| 3 | Sacred Pipeline | 20-25h | CRITICAL | ⬜ Not Started |
| 4 | Entity Services | 25-30h | HIGH | ⬜ Not Started |
| 5 | Reviews & Social | 12-15h | HIGH | ⬜ Not Started |
| 6 | Moderation & Admin | 10-12h | HIGH | ⬜ Not Started |
| 7 | Media & Photos | 8-10h | MEDIUM | ⬜ Not Started |
| 8 | Search & Discovery | 8-10h | MEDIUM | ⬜ Not Started |
| 9 | Timeline & History | 6-8h | MEDIUM | ⬜ Not Started |
| 10 | Users & Profiles | 8-10h | MEDIUM | ⬜ Not Started |
| 11 | Contact & Misc | 6-8h | LOW | ⬜ Not Started |
| 12 | Next.js Pages Migration | 45-55h | HIGH | ⬜ Not Started |
| 13 | Next.js Optimization | 15-20h | HIGH | ⬜ Not Started |
| 14 | Cleanup & Testing | 15-18h | CRITICAL | ⬜ Not Started |

---

## 🚨 Critical Path

**You MUST complete phases in this order:**

1. **Phase 1** (Foundation) - Everything depends on this
2. **Phase 2** (Authentication) - Most features require auth
3. **Phase 3** (Sacred Pipeline) - The heart of ThrillWiki
4. **Phase 4** (Entity Services) - Required for Phase 12

After Phase 4, you can work on Phases 5-11 in parallel or any order.

**Phase 12** must wait for Phases 1-4 to be complete.  
**Phase 13** must be last.

---

## 📚 Phase Documents

Each phase has a dedicated document with detailed checklists:

- [Phase 1: Foundation](./PHASE_01_FOUNDATION.md)
- [Phase 2: Authentication](./PHASE_02_AUTHENTICATION.md)
- [Phase 3: Sacred Pipeline](./PHASE_03_SACRED_PIPELINE.md)
- [Phase 4: Entity Services](./PHASE_04_ENTITY_SERVICES.md)
- [Phase 5: Reviews & Social](./PHASE_05_REVIEWS_SOCIAL.md)
- [Phase 6: Moderation & Admin](./PHASE_06_MODERATION_ADMIN.md)
- [Phase 7: Media & Photos](./PHASE_07_MEDIA_PHOTOS.md)
- [Phase 8: Search & Discovery](./PHASE_08_SEARCH_DISCOVERY.md)
- [Phase 9: Timeline & History](./PHASE_09_TIMELINE_HISTORY.md)
- [Phase 10: Users & Profiles](./PHASE_10_USERS_PROFILES.md)
- [Phase 11: Contact & Misc](./PHASE_11_CONTACT_MISC.md)
- [Phase 12: Next.js Pages Migration](./PHASE_12_PAGES_MIGRATION.md)
- [Phase 13: Next.js Optimization](./PHASE_13_NEXTJS_OPTIMIZATION.md)
- [Phase 14: Cleanup & Testing](./PHASE_14_CLEANUP_TESTING.md)

### Additional Guides

- [Next.js 15 Migration Guide](./NEXTJS_15_MIGRATION_GUIDE.md)
- [Environment Variables Guide](./ENVIRONMENT_VARIABLES.md)
- [Bun Setup & Usage](./BUN_GUIDE.md)

---

## 🎯 Success Criteria

### Code Quality
- [ ] Zero `import ... from '@supabase/supabase-js'` in codebase
- [ ] Zero `supabase.` method calls
- [ ] All TypeScript errors resolved
- [ ] All linter warnings addressed
- [ ] Test coverage >70% for services

### Functionality
- [ ] All authenticated features work
- [ ] Sacred Pipeline intact: Form → Submission → Moderation → Approval
- [ ] All entity CRUD operations work
- [ ] Search functional
- [ ] Reviews functional
- [ ] Photos functional
- [ ] Moderation queue functional
- [ ] No console errors

### Performance
- [ ] Page load times <2s
- [ ] API response times <500ms
- [ ] No memory leaks
- [ ] Proper caching

---

## 🚨 Critical Rules

1. **Sacred Pipeline is SACRED** - Never bypass moderation
2. **Test as you go** - Don't build everything then test
3. **Keep Supabase temporarily** - Only remove in Phase 13
4. **Commit frequently** - Small, atomic commits
5. **Document changes** - Update docs as you go
6. **No hallucinations** - Only fix REAL problems
7. **Keep it simple** - No feature bloat

---

## 📊 Progress Tracking

Update this section as you complete phases:

**Started:** [Date]  
**Current Phase:** Phase X  
**Completed Phases:** 0/14  
**Estimated Completion:** [Date]

---

## 🔗 Related Documentation

- Django API Documentation: `django/API_GUIDE.md`
- Django Admin Guide: `django/ADMIN_GUIDE.md`
- Sacred Pipeline Audit: `django/SACRED_PIPELINE_AUDIT_AND_IMPLEMENTATION_PLAN.md`
- Complete Migration Audit: `django/COMPLETE_MIGRATION_AUDIT.md`

---

## ⚠️ Important Notes

- **Django Backend is Ready** - All APIs exist and work
- **171 Files Need Migration** - From Supabase to Django service layer  
- **Framework Migration** - React SPA → Next.js 15 App Router
- **Package Manager** - Use Bun (not npm/yarn)
- **Environment Variables** - NO hardcoded URLs or keys
- **entitySubmissionHelpers.ts** - 1,200+ lines, most critical file
- **Sacred Pipeline** - NEVER bypass moderation (except moderators)
- **URL Preservation** - All existing URLs must work identically
- **No Data Loss** - All functionality must be preserved
- **No Feature Loss** - 100% feature parity required

## 🌍 Environment Variables

All configuration must use environment variables:

```bash
# .env.local (Next.js)
NEXT_PUBLIC_DJANGO_API_URL=https://api.thrillwiki.com
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=xxx
NEXT_PUBLIC_CLOUDFLARE_ACCOUNT_ID=xxx
CLOUDFLARE_API_TOKEN=xxx
```

See [ENVIRONMENT_VARIABLES.md](./ENVIRONMENT_VARIABLES.md) for complete guide.

## 📦 Bun Package Manager

All npm commands are replaced with Bun:

```bash
bun install              # Install dependencies
bun run dev             # Start development server
bun run build           # Production build
bun test                # Run tests
bun add package-name    # Add dependency
```

See [BUN_GUIDE.md](./BUN_GUIDE.md) for complete guide.

---

## 🆘 Need Help?

If stuck on a phase:
1. Review the phase document thoroughly
2. Check Django API endpoints in `django/api/v1/endpoints/`
3. Review existing services in `src/services/reports/` as example
4. Test with Postman/curl against Django API
5. Don't proceed until current phase is solid