docs(migration-plan): add comprehensive Next.js migration plan

Introduces `MIGRATION_PLAN.md`, detailing the strategic roadmap for migrating
the Islamic Da'wah website from its vanilla stack to Next.js. The plan
prioritizes user experience continuity and content accessibility.

Added:
- A detailed 6-phase, 12-week migration plan covering:
  - Islamic Content & Navigation
  - Audio System enhancements
  - PDF Integration & Interactive Content
  - Video Content & Advanced Features
  - Forms & Analytics
  - Multilingual & PWA Features
- Sections on migration methodology, development approach, content strategy,
  and technical considerations (Next.js 15, Tailwind v4).
- Defined success metrics, risk mitigation strategies, and an
  implementation timeline.
- An analysis of the current architecture, including existing tech stack,
  asset structure, and content organization.
- Highlights accelerated migration benefits, leveraging existing Islamic
  theme colors, audio player styles, and responsive layouts for direct
  conversion to Tailwind v4.
- Notes on the already complete Next.js 15 foundation with Tailwind v4
  configuration, base UI components, and layout structure, enabling an
  immediate start to Phase 1.

Author: aramb-dev

MIGRATION_PLAN.md

@@ -0,0 +1,296 @@
+# Islamic Da'wah Website Migration Plan: Vanilla → Next.js
+
+## Migration Strategy Overview
+
+This plan prioritizes **user experience continuity** and **content accessibility** while modernizing the technical stack. We'll migrate incrementally to maintain the Islamic educational mission and ensure zero downtime.
+
+## **Phase 1: Islamic Content & Navigation (Weeks 1-2)**
+*Priority: CRITICAL - Essential for site functionality*
+
+### 1.1 Islamic Branding & Content Migration ✅ FOUNDATION READY
+- **Targets**:
+  - [ ] Update layout.tsx with Islamic metadata and fonts (DM Sans + Inter)
+  - [ ] Replace boilerplate content with Islamic welcome message
+  - [ ] Add Islamic color palette to Tailwind config (`#132a1a`, `#e7d296`)
+  - [ ] Migrate favicon and Islamic branding assets
+- **Timeline**: Week 1
+
+### 1.2 Navigation Component Conversion
+- **Targets**:
+  - [ ] Convert existing navbar to Islamic navigation structure
+  - [ ] Add multilingual dropdown menus (English, Spanish, Mandarin)
+  - [ ] Implement audiobook dropdown navigation
+  - [ ] Add video and audio content navigation sections
+  - [ ] Convert existing responsive mobile navigation
+- **Timeline**: Week 1
+
+### 1.3 Homepage Islamic Content
+- **Targets**:
+  - [ ] Replace boilerplate hero with Islamic welcome content
+  - [ ] Add "What is Islam?", "Who is Allah?", "What is Prayer?" content cards
+  - [ ] Implement modal system for educational content
+  - [ ] Add contact section with masjid information
+  - [ ] Add "How to become Muslim" content
+  - [ ] Convert link copying functionality
+- **Timeline**: Week 2
+
+## **Phase 2: Audio System (Weeks 2-4)**
+*Priority: HIGH - Core feature for Islamic education*
+
+### 2.1 Audio Player Component Enhancement
+- **Targets**: ✅ BASE AUDIOPLAYER.TSX EXISTS
+  - [ ] Enhance existing AudioPlayer.tsx with Web Audio API features
+  - [ ] Add progress bar with scrubbing functionality
+  - [ ] Implement volume control with gain nodes
+  - [ ] Add Media Session API integration for background play
+  - [ ] Apply Islamic theming to match existing design
+  - [ ] Convert metadata system from `/assets/js/audio.js`
+- **Timeline**: Week 2-3
+
+### 2.2 Audio Content Pages
+- **Targets**:
+  - [ ] Create `/audiobook/a-glimpse-into-the-religion-of-islam/` page
+  - [ ] Create `/audiobook/un-vistazo-dentro-de-la-religion-del-islam/` page  
+  - [ ] Create `/audiobook/a-glimpse-into-the-religion-of-islam-mandarin/` page
+  - [ ] Create `/audio/comprehensive-guide-new-muslim/` page
+  - [ ] Create `/audio/listen-to-quran/` page
+  - [ ] Add Quran recitation components (Arabic/English Fatihah)
+  - [ ] Implement PDF book viewer integration
+- **Timeline**: Week 3-4
+
+## **Phase 3: PDF Integration & Interactive Content (Weeks 4-6)**
+*Priority: HIGH - Educational resource access*
+
+### 3.1 PDF Viewer System
+- **Targets**:
+  - [ ] Implement React-PDF or PDF.js integration for Next.js
+  - [ ] Create PDF viewer component for Islamic educational materials
+  - [ ] Replace DFlip.js with modern React PDF solution
+  - [ ] Add PDF download functionality
+  - [ ] Ensure mobile-responsive PDF viewing
+  - [ ] Migrate PDF assets from `/assets/pdf/`
+- **Timeline**: Week 4-5
+
+### 3.2 Modal & Interactive Content System
+- **Targets**:
+  - [ ] Create reusable Modal component (replacing Fusilli.js)
+  - [ ] Implement "Who is Allah?" educational modal
+  - [ ] Implement "What is Prayer?" educational modal  
+  - [ ] Implement "What is Islam?" educational modal
+  - [ ] Implement "How to become Muslim" modal
+  - [ ] Add ARIA-compliant accessibility features
+  - [ ] Ensure responsive design for mobile devices
+- **Timeline**: Week 5-6
+
+## **Phase 4: Video Content & Advanced Features (Weeks 6-8)**
+*Priority: MEDIUM - Supplementary educational content*
+
+### 4.1 Video Integration
+- **Targets**:
+  - [ ] Create `/video/wudu-video/` page (How to make Wudū)
+  - [ ] Create `/video/prayer-video/` page (How to Pray)
+  - [ ] Implement responsive video player component
+  - [ ] Add video accessibility features (captions, descriptions)
+  - [ ] Optimize video loading and performance
+- **Timeline**: Week 6-7
+
+### 4.2 Search & Performance Optimization
+- **Targets**:
+  - [ ] Implement site-wide search functionality for Islamic content
+  - [ ] Optimize image assets (convert to WebP)
+  - [ ] Implement performance monitoring
+  - [ ] Add SEO enhancements for Islamic content discovery
+  - [ ] Optimize audio file loading and caching
+- **Timeline**: Week 7-8
+
+## **Phase 5: Forms & Analytics (Weeks 8-10)**
+*Priority: MEDIUM - User engagement features*
+
+### 5.1 Contact Forms
+- **Targets**:
+  - [ ] Create modern contact form component with validation
+  - [ ] Implement server-side form processing
+  - [ ] Integrate reCAPTCHA v2 (existing implementation)
+  - [ ] Add email notification system
+  - [ ] Convert existing form submission logic to Next.js API routes
+- **Timeline**: Week 8-9
+
+### 5.2 Analytics & Monitoring
+- **Targets**:
+  - [ ] Integrate Google Analytics 4 with Next.js App Router
+  - [ ] Migrate Microsoft Clarity integration  
+  - [ ] Implement performance monitoring
+  - [ ] Add error tracking and reporting
+  - [ ] Ensure privacy-compliant analytics for Islamic content
+- **Timeline**: Week 9-10
+
+## **Phase 6: Multilingual & PWA Features (Weeks 10-12)**
+*Priority: LOW - Enhancement features*
+
+### 6.1 Internationalization (i18n)
+- **Targets**:
+  - [ ] Set up Next.js i18n routing configuration
+  - [ ] Create language-specific content management system
+  - [ ] Implement language switcher component
+  - [ ] Add RTL support for Arabic content  
+  - [ ] Migrate Spanish and Mandarin content with proper routing
+- **Timeline**: Week 10-11
+
+### 6.2 Progressive Web App Enhancement
+- **Targets**:
+  - [ ] Enhance existing manifest for Islamic content
+  - [ ] Implement service worker for offline Islamic educational content
+  - [ ] Add app-like installation experience
+  - [ ] Implement push notifications for Islamic reminders/content
+  - [ ] Optimize for mobile Islamic learning experience
+- **Timeline**: Week 11-12
+
+---
+
+## **Migration Methodology**
+
+### Development Approach
+1. **Parallel Development**: Build Next.js version alongside existing site
+2. **Feature Parity**: Ensure 100% functional equivalence before switching
+3. **A/B Testing**: Gradual rollout with user feedback collection
+4. **Rollback Plan**: Maintain vanilla version as backup
+
+### Content Migration Strategy
+1. **Asset Optimization**: Convert to modern formats (WebP, optimized audio)
+2. **SEO Preservation**: Maintain all URLs and metadata
+3. **Performance Baseline**: Measure and improve on current metrics
+4. **Accessibility Enhancement**: Improve WCAG compliance
+
+### Technical Considerations
+- **Framework**: Next.js 15 with App Router
+- **Styling**: Tailwind v4 (converting from existing Bootstrap/SCSS - **STYLES ALREADY IMPLEMENTED**)
+- **State Management**: React Context for audio players
+- **Deployment**: Vercel or similar with CDN optimization
+- **Monitoring**: Real-time performance and error tracking
+- **Style Migration**: Direct conversion from `/assets/scss/main.scss` to Tailwind v4 classes
+
+---
+
+## **Success Metrics**
+
+### Performance Targets
+- **Lighthouse Scores**: 90+ across all categories
+- **Core Web Vitals**: Green ratings for LCP, FID, CLS
+- **Audio Playback**: 99%+ reliability
+- **Mobile Performance**: Perfect responsive experience
+
+### Content Quality
+- **SEO**: Maintain or improve search rankings for Islamic content
+- **Accessibility**: WCAG 2.1 AA compliance
+- **Islamic Content Integrity**: Zero content degradation
+- **Multilingual Support**: Seamless language switching
+
+---
+
+## **Risk Mitigation**
+
+### Technical Risks
+- **Audio System**: Extensive testing of Web Audio API across browsers
+- **PDF Rendering**: Fallback systems for different devices
+- **Performance**: Regular performance audits and optimization
+- **Mobile Experience**: Comprehensive device testing
+
+### Content Risks
+- **Islamic Content Integrity**: Rigorous testing of all religious content
+- **Cultural Sensitivity**: Preserve respectful presentation of Islamic teachings
+- **Accessibility**: Ensure Islamic content is accessible to all users
+- **Multilingual Accuracy**: Professional review of translations
+
+---
+
+## **Implementation Timeline**
+
+| Phase | Duration | Key Deliverables | Critical Path |
+|-------|----------|------------------|---------------|
+| 1 | Weeks 1-2 | Islamic Content + Navigation | ✅ Critical |
+| 2 | Weeks 2-4 | Audio System | ✅ Critical |
+| 3 | Weeks 4-6 | PDF + Modals | ✅ Critical |
+| 4 | Weeks 6-8 | Video + Search | ⚠️ Medium |
+| 5 | Weeks 8-10 | Forms + Analytics | ⚠️ Medium |
+| 6 | Weeks 10-12 | i18n + PWA | ℹ️ Enhancement |
+
+---
+
+## **Current Architecture Analysis**
+
+### Existing Tech Stack
+- **Frontend**: Vanilla HTML5, Bootstrap 5.3.3, custom SCSS
+- **JavaScript**: Vanilla JS with Web Audio API, Modal system
+- **External Libraries**: DFlip.js (PDF), Fusilli.js (modals), Axios
+- **Analytics**: Google Analytics, Microsoft Clarity
+- **Audio**: Custom player with Media Session API
+
+### Asset Structure
+```
+assets/
+├── css/        # Compiled CSS + Bootstrap/Bulma
+├── scss/       # Custom SCSS with Islamic theming
+├── js/         # Vanilla JS modules (audio.js, etc.)
+├── audio/      # MP3 files (audiobooks, Quran)
+├── pdf/        # Educational materials
+├── img/        # Images with WebP optimization
+└── dflip/      # PDF reader library
+```
+
+### Content Organization
+- **Multilingual**: English (primary), Spanish, Mandarin
+- **Audio Content**: Islamic audiobooks, Quran recitations
+- **Educational Materials**: PDFs, videos, interactive content
+- **SEO**: Structured data, social sharing optimization
+
+---
+
+## **Next Steps**
+
+1. **Phase 1 Kickoff**: Set up Next.js foundation in `/new` directory
+2. **Component Library**: Create reusable Islamic-themed components
+3. **Asset Migration**: Optimize and migrate static assets
+4. **Audio System**: Rebuild custom audio player in React
+5. **Content Migration**: Transfer educational content with SEO preservation
+6. **Testing**: Comprehensive testing across devices and browsers
+7. **Deployment**: Gradual rollout with monitoring and feedback
+
+This migration will modernize your Islamic educational platform while preserving its core mission and ensuring an excellent user experience for those seeking to learn about Islam.
+
+## **ACCELERATED MIGRATION BENEFITS**
+
+### Existing Assets Advantage
+- **Islamic Theme Colors**: Already defined (`#132a1a`, `#e7d296`) in `/assets/scss/main.scss`
+- **Audio Player Styles**: Complete custom player design ready for Tailwind conversion
+- **Modal System**: Fusilli.js modal styles can be directly mapped to Tailwind v4
+- **Responsive Layout**: Bootstrap grid system easily converts to Tailwind v4 grid
+- **Component Styles**: All UI components already styled and tested
+
+### Conversion Strategy
+1. **Style Mapping**: Direct 1:1 conversion from SCSS variables to Tailwind v4 config
+2. **Component Library**: Create Tailwind v4 components matching existing designs exactly
+3. **Islamic Theming**: Preserve exact color palette and Islamic design elements
+4. **Responsive Breakpoints**: Maintain current mobile-responsive behavior
+
+### Time Savings
+- **50% faster styling phase** - No design decisions needed
+- **Immediate visual consistency** - Styles already proven and optimized
+- **Focus on functionality** - More time for React component logic and performance
+- **Reduced testing** - Visual regression testing simplified
+
+**NEW ACCELERATED TIMELINE: 12 weeks total (vs original 13 weeks)**
+
+## **🚀 FOUNDATION ALREADY COMPLETE**
+
+### ✅ What's Already Implemented in `/new/`:
+- **Next.js 15 App Router**: Complete foundation with TypeScript
+- **Tailwind v4**: Configured and ready for Islamic theming
+- **UI Components**: Button, Card, Input, AudioPlayer.tsx base
+- **Layout Structure**: Root layout with font configuration
+- **Boilerplate Page**: Ready for Islamic content replacement
+- **Component Architecture**: Organized `/src/components/` structure
+
+### 🎯 Ready to Start:
+- Phase 1 can begin immediately with content migration
+- AudioPlayer.tsx base exists - just needs Islamic features
+- Styling system ready for direct SCSS → Tailwind conversion