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 2: Authentication
• Phase 3: Sacred Pipeline
• Phase 4: Entity Services
• Phase 5: Reviews & Social
• Phase 6: Moderation & Admin
• Phase 7: Media & Photos
• Phase 8: Search & Discovery
• Phase 9: Timeline & History
• Phase 10: Users & Profiles
• Phase 11: Contact & Misc
• Phase 12: Next.js Pages Migration
• Phase 13: Next.js Optimization
• Phase 14: Cleanup & Testing

Additional Guides

• Next.js 15 Migration Guide
• Environment Variables Guide
• Bun Setup & Usage

---

🎯 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:

# .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 for complete guide.

📦 Bun Package Manager

All npm commands are replaced with Bun:

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