# Redirect-to-Source: Visual Flow Guide

## 🎯 The Problem Solved

**Before**: Users always went to dashboard after creating website  
**After**: Users return to their original page (crawl, reports, etc.)

---

## 📱 User Journey: From Crawl Page

```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  USER ON CRAWL PAGE (/crawl)                               │
│  - Empty state or existing websites                         │
│  - Wants to create another project                          │
│                                                             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  CLICK "Create Project" BUTTON                              │
│  Link: /onboarding?redirect=crawl                           │
│                                                             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  ONBOARDING PAGE LOADS                                      │
│                                                             │
│  Controller receives: ?redirect=crawl                       │
│  ✓ Validates against whitelist                             │
│  ✓ Passes to view: $redirect = 'crawl'                     │
│  ✓ Stores in JS: onboardingRedirect = '/crawl'            │
│                                                             │
│  USER SEES:                                                 │
│  - "Skip for now →" link points to /crawl                 │
│  - "Go to Crawl" button (not dashboard)                   │
│  - 5-step wizard with Website step = ACTIVE               │
│                                                             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  USER CLICKS "Continue" ON WEBSITE STEP                     │
│                                                             │
│  JS calls: handleConnect('website')                        │
│  ↓                                                          │
│  Checks: WCCreateProjectModal exists?                      │
│  ↓                                                          │
│  YES → Sets: window.wcProjectModalRedirect = '/crawl'      │
│  ↓                                                          │
│  Opens modal: WCCreateProjectModal.open()                  │
│                                                             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  WEBSITE CREATION MODAL OPENS                               │
│  Modal already has: window.wcProjectModalRedirect = '/crawl'│
│                                                             │
│  USER FILLS FORM:                                           │
│  • Domain: example.com                                      │
│  • Max pages: 500                                           │
│  • Verification: DNS TXT Record                             │
│  • Sitemap: (optional)                                      │
│                                                             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  CLICKS "Create Project" BUTTON                             │
│                                                             │
│  Form submission → POST /api/v1/websites                   │
│  ├─ Domain: https://example.com                            │
│  ├─ Max pages: 500                                         │
│  ├─ Verification: dns                                      │
│  └─ Sitemap: null                                          │
│                                                             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  API RESPONSE: SUCCESS                                      │
│                                                             │
│  Response: { success: true, data: { id: 123, ... } }       │
│                                                             │
│  Modal JS catches success:                                  │
│  ├─ Shows success message: "✅ Project created!"           │
│  ├─ Starts timer: 1.5 seconds                              │
│  ├─ Checks: window.wcProjectModalRedirect?                │
│  └─ YES! Value = '/crawl'                                  │
│                                                             │
└──────────────────────┬──────────────────────────────────────┘
                       │
            [1.5 seconds pass]
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  AUTO-REDIRECT TO SOURCE PAGE                               │
│                                                             │
│  window.location.href = '/crawl'                           │
│                                                             │
│  ✓ NOT: window.location.reload() [old behavior]            │
│  ✓ NOT: /dashboard [dashboard behavior]                    │
│  ✓ YES: /crawl [original source page]                     │
│                                                             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  USER BACK ON CRAWL PAGE (/crawl)                           │
│                                                             │
│  ✓ New website is now visible in the list                  │
│  ✓ Can immediately start crawling                          │
│  ✓ No wasted steps back to dashboard                       │
│  ✓ Smooth, predictable user experience                     │
│                                                             │
│  🎉 USER HAPPY - TASK COMPLETE                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## 🔄 Comparison: Different Entry Points

### Scenario 1: From Dashboard (Modal)
```
Dashboard ──→ Click modal button ──→ Modal (embedded)
  ↓
Create website
  ↓
wcProjectModalRedirect = UNDEFINED (not set)
  ↓
window.location.reload()
  ↓
Back to Dashboard ✓
```

### Scenario 2: From Crawl Page (Redirect)
```
Crawl ──→ Click button ──→ /onboarding?redirect=crawl
  ↓
Click "Continue"
  ↓
Modal opens (wcProjectModalRedirect = /crawl SET)
  ↓
Create website
  ↓
window.location.href = '/crawl'
  ↓
Back to Crawl ✓
```

### Scenario 3: From Reports Page (Redirect)
```
Reports ──→ Click button ──→ /onboarding?redirect=reports
  ↓
Create website
  ↓
Redirect to /reports ✓
```

---

## 🛡️ Security Flow: Invalid Redirects

```
User tries: /onboarding?redirect=evil.com
  ↓
OnboardingController receives: redirect = 'evil.com'
  ↓
Validates against whitelist:
  ['dashboard', 'crawl', 'website', 'reports', 'audit', 'keywords', 'rank-tracking']
  ↓
'evil.com' NOT in whitelist
  ↓
Default to 'dashboard'
  ↓
$redirect = 'dashboard'
  ↓
User sees "Go to dashboard" button
  ↓
No open redirect vulnerability ✓
```

---

## 📊 Code Flow: How Redirect Flows Through System

```
┌──────────────────────────────┐
│ URL with redirect parameter  │
│ /onboarding?redirect=crawl   │
└────────────┬─────────────────┘
             │
             ▼
┌──────────────────────────────────────────────────┐
│ OnboardingController::index()                    │
│                                                  │
│ $redirect = $this->request->getGet('redirect')  │
│ → 'crawl'                                        │
│                                                  │
│ Validate against whitelist                      │
│ → passes ✓                                      │
│                                                  │
│ $data['redirect'] = 'crawl'                     │
│ return $this->render('onboarding/index', $data)│
└────────────┬─────────────────────────────────────┘
             │
             ▼
┌──────────────────────────────────────────────────┐
│ onboarding/index.php View                        │
│                                                  │
│ Receives: $redirect = 'crawl'                   │
│                                                  │
│ In HTML:                                         │
│ <a href="<?= site_url($redirect) ?>">           │
│    Skip for now → /crawl                        │
│ </a>                                             │
│                                                  │
│ <a href="<?= site_url($redirect) ?>">           │
│    Go to Crawl                                   │
│ </a>                                             │
│                                                  │
│ In JavaScript:                                   │
│ const onboardingRedirect = '/crawl'              │
│ (stored in JS global variable)                   │
└────────────┬─────────────────────────────────────┘
             │
             ▼
┌──────────────────────────────────────────────────┐
│ WCOnboarding.handleConnect() - JS               │
│                                                  │
│ if (step === 'website') {                       │
│   window.wcProjectModalRedirect = onboarding    │
│   Redirect = '/crawl'  ← PASS REDIRECT           │
│                                                  │
│   WCCreateProjectModal.open()                   │
│ }                                                │
└────────────┬─────────────────────────────────────┘
             │
             ▼
┌──────────────────────────────────────────────────┐
│ create-project-modal.php - JS                   │
│                                                  │
│ User submits form                               │
│ POST /api/v1/websites                           │
│                                                  │
│ Success response received:                      │
│ if (window.wcProjectModalRedirect) {            │
│   window.location.href =                        │
│     window.wcProjectModalRedirect  ← USE REDIRECT
│   → '/crawl'                                    │
│ } else {                                         │
│   window.location.reload()                      │
│ }                                                │
└────────────┬─────────────────────────────────────┘
             │
             ▼
┌──────────────────────────────────────────────────┐
│ Browser redirects to /crawl                      │
│                                                  │
│ User sees their newly created website           │
│ Ready to start crawling immediately ✓           │
└──────────────────────────────────────────────────┘
```

---

## 🧪 Testing Matrix

| Test Case | Input | Expected Output | Status |
|-----------|-------|-----------------|--------|
| Redirect to Crawl | `/onboarding?redirect=crawl` | Button: "Go to Crawl", Link to /crawl | ✅ |
| Redirect to Reports | `/onboarding?redirect=reports` | Button: "Go to Reports", Link to /reports | ✅ |
| No Redirect | `/onboarding` | Button: "Go to dashboard", Link to /dashboard | ✅ |
| Invalid Redirect | `/onboarding?redirect=evil.com` | Treated as dashboard, safe redirect | ✅ |
| Modal Dashboard | Modal opened on /dashboard | No redirect set, page reloads | ✅ |
| Website Creation Success | Complete form in modal | Redirects to source (if redirect set) | ✅ |
| Website Creation Error | API returns error | Shows error, no redirect | ✅ |

---

## 🎨 UI Changes by Redirect Value

```
Redirect Parameter    →    Button Text              Skip Link Points To
────────────────────────────────────────────────────────────────────
dashboard              →    "Go to dashboard"       /dashboard
crawl                  →    "Go to Crawl"           /crawl
reports                →    "Go to Reports"         /reports
audit                  →    "Go to Audit"           /audit
keywords               →    "Go to Keywords"        /keywords
rank-tracking          →    "Go to Rank-tracking"   /rank-tracking
website                →    "Go to Website"         /website
(invalid/missing)      →    "Go to dashboard"       /dashboard (default)
```

---

## 💡 Key Design Decisions

1. **Whitelist Validation**: Only specific known pages, not arbitrary URLs
2. **Global Variable**: Simple way to pass data from controller to modal
3. **1.5 Second Delay**: Gives user time to see success message
4. **Backward Compatible**: Modal works on dashboard without redirect
5. **Default Fallback**: Invalid redirects safely default to dashboard
6. **Site URL Helper**: Uses CodeIgniter's helper for proper URL construction

---

## 📝 Implementation Checklist

- ✅ Extract redirect parameter in controller
- ✅ Validate against whitelist
- ✅ Pass to view
- ✅ Update header skip link
- ✅ Update footer button
- ✅ Store in JavaScript variable
- ✅ Pass to modal via global variable
- ✅ Use in modal redirect logic
- ✅ All syntax validated
- ✅ Routes working
- ✅ Documentation complete

---

*Created: 2026-08-18*  
*Status: Ready for Deployment*