# WordPress & Next.js Integration Guide

How WordPress and Next.js work together in the Planit AI project.

## 🔗 Architecture Overview

```
┌─────────────────────────────────┐
│      Next.js Frontend           │
│   (React/TypeScript/Next.js)    │
│   Port: 3000 (dev) / 80 (prod)  │
└──────────────┬──────────────────┘
               │
               │ HTTP/REST API
               │ (GET/POST requests)
               │
┌──────────────▼──────────────────┐
│      WordPress Backend           │
│   (PHP/MySQL/WordPress CMS)     │
│   Port: 80/443                   │
└──────────────────────────────────┘
```

## 📡 API Integration

### WordPress REST API

The Next.js frontend communicates with WordPress via the REST API:

**Base URL:** `https://your-wordpress-domain.com/api/wp/v2`

### Main Endpoints

#### 1. Blog Posts & News

```typescript
// Get all posts
GET /api/wp/v2/posts?_embed

// Get post by slug
GET /api/wp/v2/posts?slug={slug}&_embed

// Get posts by category
GET /api/wp/v2/posts?categories={id}&_embed
```

**Response includes:**
- Post content (HTML from block editor)
- Featured images
- Categories and tags
- Author information
- Publication dates

#### 2. Contact Form Submission

```typescript
// Submit contact form
POST /api/contact-form-7/v1/contact-forms/{form_id}/feedback

// Form data includes:
- name, email, company, inquiry type, message
- g-recaptcha-response (reCAPTCHA token)
```

## 🔄 Data Flow

### Blog/News Content Flow

```
1. User visits Next.js blog page
   ↓
2. Next.js calls WordPress API
   GET /api/wp/v2/posts?categories=2
   ↓
3. WordPress returns JSON with posts
   ↓
4. Next.js renders posts with React components
   ↓
5. User clicks on a post
   ↓
6. Next.js calls WordPress API
   GET /api/wp/v2/posts?slug=post-slug
   ↓
7. WordPress returns full post content (HTML)
   ↓
8. Next.js renders content using WordPressContentRenderer
```

### Contact Form Flow

```
1. User fills contact form on Next.js
   ↓
2. reCAPTCHA v3 executes (invisible)
   ↓
3. Form data + reCAPTCHA token sent to WordPress
   POST /api/contact-form-7/v1/contact-forms/219/feedback
   ↓
4. WordPress validates reCAPTCHA
   ↓
5. WordPress sends email notification
   ↓
6. WordPress returns success/error response
   ↓
7. Next.js shows success/error message to user
```

## 🔧 Configuration

### Next.js Configuration

**File:** `nextjs/lib/api.ts`

```typescript
// WordPress API base URL
const API_BASE = process.env.NEXT_PUBLIC_WP_API_BASE;

// Contact form endpoint
const FORM_URL = `${API_BASE}/../contact-form-7/v1/contact-forms/219/feedback`;
```

**Environment Variables:**
```env
NEXT_PUBLIC_WP_API_BASE=https://your-wordpress-domain.com/api/wp/v2
NEXT_PUBLIC_RECAPTCHA_SITE_KEY=your_site_key
```

### WordPress Configuration

**Contact Form 7:**
- Form ID: 219 (or check your installation)
- reCAPTCHA: Configured in **Contact > Integration**
- Form fields: name, email, company, inquiry type, message

**REST API:**
- Enabled by default in WordPress
- Accessible at `/api/wp/v2`
- No authentication required for public endpoints

## 📝 Content Management

### WordPress Admin

Content editors use WordPress admin panel to:
- Create/edit blog posts
- Create/edit news articles
- Upload images and media
- Manage categories and tags
- Configure contact forms

### Next.js Frontend

The frontend automatically:
- Fetches latest content from WordPress API
- Caches content for performance
- Renders WordPress block editor HTML
- Displays images and media
- Handles form submissions

## 🎨 WordPress Block Editor Integration

The Next.js app includes a custom renderer for WordPress block editor content:

**Component:** `nextjs/components/blogs/WordPressContentRenderer.tsx`

**Features:**
- Parses WordPress block editor HTML
- Renders headings, paragraphs, images, lists, quotes, tables
- Applies styling consistent with design system
- Handles nested content structures

**Usage:**
```typescript
<WordPressContentRenderer 
  content={post.content.rendered} 
/>
```

## 🔐 Security

### reCAPTCHA Integration

1. **Frontend (Next.js):**
   - Executes reCAPTCHA v3 on form submission
   - Gets token from Google
   - Sends token with form data

2. **Backend (WordPress):**
   - Receives token in form submission
   - Validates token with Google
   - Blocks submissions if validation fails

### CORS Configuration

If you see CORS errors:
- WordPress REST API should allow requests from Next.js domain
- Install "REST API - Filter Fields" plugin
- Or configure in `.htaccess`:
  ```apache
  Header set Access-Control-Allow-Origin "*"
  ```

## 🚀 Deployment Considerations

### WordPress Deployment

- Deploy to traditional hosting (cPanel, etc.)
- Ensure REST API is accessible
- Configure SSL/HTTPS
- Set up backups

### Next.js Deployment

**Option 1: Vercel**
- Automatic deployments
- Environment variables in dashboard
- HTTPS by default

**Option 2: Custom Server**
- Build: `yarn build`
- Run: `yarn start`
- Use PM2 for process management
- Configure Nginx reverse proxy

### Environment Variables

**Development:**
```env
NEXT_PUBLIC_WP_API_BASE=http://localhost:8000/api/wp/v2
NEXT_PUBLIC_RECAPTCHA_SITE_KEY=test_key
```

**Production:**
```env
NEXT_PUBLIC_WP_API_BASE=https://your-wordpress-domain.com/api/wp/v2
NEXT_PUBLIC_RECAPTCHA_SITE_KEY=production_key
```

## 🔍 Testing Integration

### Test API Connection

```bash
# Test WordPress API
curl https://your-wordpress-domain.com/api/wp/v2/posts?per_page=1

# Should return JSON with post data
```

### Test Contact Form

1. Fill out form on Next.js site
2. Check browser console for errors
3. Verify email is received
4. Check WordPress admin for submission

### Test Content Rendering

1. Create test post in WordPress
2. Verify it appears on Next.js blog page
3. Check individual post page renders correctly
4. Verify images and media load

## 🐛 Common Issues

### Issue: API Not Accessible

**Symptoms:**
- Next.js shows loading/error states
- Network requests fail

**Solutions:**
- Verify WordPress URL is correct
- Check CORS settings
- Ensure WordPress REST API is enabled
- Test API endpoint directly in browser

### Issue: Images Not Loading

**Symptoms:**
- Placeholder images shown
- Broken image links

**Solutions:**
- Check image URLs in API response
- Verify WordPress uploads directory permissions
- Update `next.config.ts` image domains
- Check CORS for image requests

### Issue: Contact Form Not Working

**Symptoms:**
- Form submission fails
- No email received
- reCAPTCHA errors

**Solutions:**
- Verify form ID matches WordPress
- Check reCAPTCHA keys are correct
- Ensure domain is in reCAPTCHA allowed domains
- Check WordPress email configuration
- Review browser console for errors

## 📚 Additional Resources

- [WordPress REST API Handbook](https://developer.wordpress.org/rest-api/)
- [Next.js Documentation](https://nextjs.org/docs)
- [Contact Form 7 API](https://contactform7.com/rest-api/)
- [Google reCAPTCHA v3](https://developers.google.com/recaptcha/docs/v3)

---

For setup instructions, see `SETUP-GUIDE.md`