# Full Migration Documentation: Joomla to Next.js 14+ (App Router)

> **Project:** Instant Assignment Help Architecture Migration  
> **Source Platform:** Joomla PHP Monolith & MySQL Database (`joomla_IAH`)  
> **Target Framework:** Next.js 14+ (App Router) + TypeScript + Tailwind CSS  
> **Status:** Production-Ready, 100% Dynamic Synchronization Enabled  

---

## Table of Contents

1. [Executive Summary & Migration Goals](#1-executive-summary--migration-goals)
2. [Technology Stack](#2-technology-stack)
3. [System Architecture & Folder Structure](#3-system-architecture--folder-structure)
4. [Data Flow & End-to-End Execution Sequence](#4-data-flow--end-to-end-execution-sequence)
5. [Joomla Backend & PHP API Bridge Layer](#5-joomla-backend--php-api-bridge-layer)
6. [Next.js API & Service Layer](#6-nextjs-api--service-layer)
7. [UI Components Architecture](#7-ui-components-architecture)
8. [Dynamic Routing & Catch-All Handler](#8-dynamic-routing--catch-all-handler)
9. [Environment Variables & Configuration](#9-environment-variables--configuration)
10. [Verification, Build & Deployment Guide](#10-verification-build--deployment-guide)

---

## 1. Executive Summary & Migration Goals

The objective of this project was to migrate the core frontend header, footer, page routing, and content presentation of **[Instant Assignment Help](https://www.instantassignmenthelp.com/)** from an legacy Joomla PHP platform to a state-of-the-art **Next.js 14+ App Router** web application.

### Key Deliverables Achieved
- **100% Dynamic Data Flow:** Header menus, mega menu categorizations, footer links, homepage banners, price calculator options, and article contents are dynamically fetched from the Joomla backend database (`joomla_IAH`).
- **Instant Admin Synchronization:** Any edit made in Joomla Admin (such as editing the homepage **Article ID `11`** or adding a new Navbar item in Joomla Menu Manager) automatically reflects on the Next.js frontend within 60 seconds (or instantly upon revalidation).
- **SEO & Performance:** Full Server-Side Rendering (SSR) and Server Components for optimal search engine crawling and fast Core Web Vitals.
- **Responsive & Accessible Design:** Mobile sliding drawer, accessible keyboard navigation (`Escape`, `ArrowDown`, `Tab`), and mobile viewports support.

---

## 2. Technology Stack

| Layer | Technology | Purpose |
| :--- | :--- | :--- |
| **Framework** | Next.js 14+ (App Router) | Server Components, routing, SSR, and Turbopack bundler |
| **Language** | TypeScript (Strict Mode) | Strong type definitions for API responses and component props |
| **Styling** | Tailwind CSS | Utility-first styling with brand palette (`#c33571`, `#1faf38`, `#0f172a`) |
| **Typography** | Google Fonts (`Inter`, `Outfit`) | Modern typography loaded via `next/font` |
| **Icons** | Lucide Icons (`lucide-react`) | Lightweight SVG icon library |
| **Database** | MySQL (`joomla_IAH`) | Native Joomla database storing articles (`JM_content`) and menus (`JM_menu`) |
| **API Bridge** | PHP REST / JSON Bridge | High-speed JSON endpoints reading directly from Joomla MySQL |

---

## 3. System Architecture & Folder Structure

```text
migration-next.js-project/
├── app/
│   ├── api/
│   │   ├── navigation/
│   │   │   └── route.ts             # GET /api/navigation (serves header & footer data)
│   │   └── home/
│   │       └── route.ts             # GET /api/home (serves index page & calculator data)
│   ├── [...slug]/
│   │   └── page.tsx                 # Dynamic Catch-All Route for ANY Joomla article
│   ├── layout.tsx                   # Root Server Layout (mounts <Header/> & <Footer/>)
│   ├── page.tsx                     # Home Page (renders hero calculator + index article 11)
│   └── globals.css                  # Global Tailwind CSS directives
├── components/
│   ├── common/
│   │   ├── Logo.tsx                 # Crisp SVG brand logo
│   │   └── Button.tsx               # Primary, Secondary, WhatsApp & Accent buttons
│   ├── home/
│   │   └── OrderCalculator.tsx      # Interactive price estimation calculator component
│   └── layout/
│       ├── Header/
│       │   ├── Header.tsx           # Server component wrapper for top bar & navbar
│       │   ├── TopBar.tsx           # Announcement, WhatsApp, Phone, Email, Region Selector
│       │   ├── Navbar.tsx           # Brand logo, NavDropdowns, Search, Cart, Login, CTAs
│       │   ├── NavDropdown.tsx      # Accessible dropdown & multi-column Mega Menu
│       │   └── MobileMenu.tsx       # Slide-out drawer menu for mobile viewports
│       └── Footer/
│           ├── Footer.tsx           # 5-column footer structure with trust badges & disclaimers
│           ├── FooterCol.tsx        # Dynamic footer column renderer
│           └── SocialLinks.tsx      # Social media links & app store download buttons
├── data/
│   ├── mockNavigation.ts            # Dynamic environment navigation data generator
│   └── mockHomeData.ts              # Dynamic environment homepage fallback data
├── services/
│   └── joomlaService.ts             # Central manager fetching from Joomla REST API / JSON Bridge
├── types/
│   ├── navigation.ts                # TypeScript interfaces for menu & footer entities
│   └── home.ts                      # TypeScript interfaces for home page & calculator
├── .env.local                       # Local environment variables
├── .env.example                     # Environment template
└── AGENTS.md                        # Architecture & onboarding guide for developers
```

---

## 4. Data Flow & End-to-End Execution Sequence

The diagram below illustrates how data flows from Joomla Admin all the way to the user's browser:

```mermaid
sequenceDiagram
    autonumber
    actor Admin as Joomla Administrator
    participant DB as MySQL (joomla_IAH)
    participant PHP as PHP API Bridge (/websites/api/)
    participant JS as Next.js joomlaService
    participant NextAPI as Next.js Route Handler (/api/*)
    participant Page as Next.js Server Page
    actor User as Web Visitor

    Admin->>DB: Saves Article 11 ("index") or creates new Menu in Joomla
    User->>Page: Requests https://domain.com/
    Page->>JS: Calls getHomePageData() / getNavigationData()
    JS->>PHP: HTTP GET http://localhost/websites/api/home.php
    PHP->>DB: SELECT introtext, fulltext FROM JM_content WHERE id=11
    DB-->>PHP: Returns article text & title
    PHP-->>JS: Returns JSON response
    JS-->>NextAPI: Formats Navigation & Article payload
    NextAPI-->>Page: Delivers structured Page Data
    Page-->>User: Renders HTML with Header, Hero Calculator & Joomla Article
```

---

## 5. Joomla Backend & PHP API Bridge Layer

To ensure zero latency and full compatibility with the user's existing Joomla database (`joomla_IAH`), three high-speed PHP endpoints were implemented in `/var/www/html/websites/api/`:

### 1. Navigation Bridge (`/var/www/html/websites/api/navigation.php`)
- **Database Query:** Queries `JM_menu` where `published = 1` and `menutype IN ('main', 'mainmenu', 'us')`.
- **Logic:** Recursively builds a 3-level tree structure (`parent_id`) for dropdowns and mega menus.
- **Output:** Returns JSON payload with all main navigation items.

### 2. Home Page Bridge (`/var/www/html/websites/api/home.php`)
- **Database Query:** `SELECT id, title, alias, introtext, \`fulltext\`, metadesc, metakey FROM JM_content WHERE id = 11 OR alias = 'index'`.
- **Note:** Backticks escape the reserved MySQL keyword `fulltext`.
- **Output:** Returns JSON containing the exact HTML content edited in Joomla Admin for article `id=11` (`index`).

### 3. Article Bridge (`/var/www/html/websites/api/article.php`)
- **Database Query:** Prepared statement querying `JM_content` by `slug` or `id`.
- **Output:** Returns full article title, introtext, fulltext, and SEO metadata.

---

## 6. Next.js API & Service Layer

### Central Service: `services/joomlaService.ts`
`JoomlaService` acts as the single entry point for all data fetching:
- **`getNavigation()`**: Fetches navigation from `/navigation.php`. Converts raw menu items into `MenuItem` objects.
- **`getHomePage()`**: Fetches homepage data from `/home.php`. Returns `HomePageResponse` with `articleContentHtml`.
- **`getArticleBySlug(slug)`**: Fetches any page from `/article.php?slug=${slug}`.

### Next.js Internal Route Handlers
- **`app/api/navigation/route.ts`**: Serves `GET /api/navigation`.
- **`app/api/home/route.ts`**: Serves `GET /api/home`.
- **Caching & Revalidation:** Configured with `{ next: { revalidate: 60 } }` to ensure content stays fresh without overloading the database.

---

## 7. UI Components Architecture

### Header System (`components/layout/Header/`)
- **`TopBar.tsx`**: Top strip displaying WhatsApp quick contact, phone, support email, 51% OFF offer banner, and region selector (UK, US, CA, NZ, MY, UAE, SG).
- **`Navbar.tsx`**: Main navigation bar with branding logo, dropdown triggers, expandable search box, cart item count, login trigger, and "Order Now" button.
- **`NavDropdown.tsx`**: Interactive Client Component supporting hover/click toggles, keyboard navigation (`Escape`, `ArrowDown`), and a multi-column **Mega Menu** for Services categories.
- **`MobileMenu.tsx`**: Sliding drawer menu with collapsible accordion items for mobile screens.

### Footer System (`components/layout/Footer/`)
- **`Footer.tsx`**: 5-column footer structure (Top Assignment Searches, Our Company, Assignment by Countries, Let Us Help You, Contact Us).
- **Trust Elements:** Displays rating badge (**4.8/5 based on 5768 Reviews**), DMCA protection badge, accepted payment methods (Visa, MasterCard, Amex, PayPal), disclaimer notice box, and copyright bar.
- **`SocialLinks.tsx`**: Social media links (Facebook, Twitter, Instagram, Pinterest, YouTube, LinkedIn) and App Store / Google Play download badges.

### Home Page & Order Calculator (`components/home/`)
- **`OrderCalculator.tsx`**: Interactive client component calculating order costs in real-time based on subject, page count, and deadline urgency, applying the 51% discount.
- **`app/page.tsx`**: Renders the Hero calculator section, followed by section `#2`: the **Joomla Index Article Content (`id=11` / `index`)** rendered via `dangerouslySetInnerHTML`.

---

## 8. Dynamic Routing & Catch-All Handler

### File: `app/[...slug]/page.tsx`

Any route accessed on the website (e.g., `/do-my-assignment`, `/essay-writing-help-uk`, `/dissertation-help`, `/about-us`, `/reviews`) is caught by `app/[...slug]/page.tsx`:

1. Extracts the URL slug (e.g. `do-my-assignment`).
2. Calls `joomlaService.getArticleBySlug(slug)`.
3. Dynamically generates metadata (`title`, `description`, `keywords`).
4. Renders the article title, breadcrumb bar, and HTML content directly from Joomla.

---

## 9. Environment Variables & Configuration

### File: `.env.local`

```env
# Base Site & API URLs
NEXT_PUBLIC_SITE_URL=https://www.instantassignmenthelp.com
NEXT_PUBLIC_CPANEL_URL=https://customerpanel.instantassignmenthelp.com
JOOMLA_API_BASE_URL=http://localhost/websites/api

# Business Contact Settings
NEXT_PUBLIC_WHATSAPP_NUM=+1 7753738777
NEXT_PUBLIC_PHONE_NUM=+1 7753738777
NEXT_PUBLIC_EMAIL=help@instantassignmenthelp.com
```

---

## 10. Verification, Build & Deployment Guide

### Automated Build Command
To compile the project and verify TypeScript types and page generation:
```bash
npm run build
```

### Build Output Summary
```text
Route (app)          Revalidate  Expire
┌ ○ /                        1m      1y
├ ○ /_not-found              1m      1y
├ ƒ /[...slug]               (Dynamic Joomla Article Catch-All)
├ ƒ /api/home                (Dynamic Home Content API)
└ ƒ /api/navigation          (Dynamic Navigation API)
```

### Running Locally
```bash
npm run dev
```
Access the application locally at `http://localhost:3000` (or `http://localhost:3001`).