# Onboarding Flow - Current Design & Implementation

## 📋 EXISTING DESIGN (Team Reference)

**File**: `public/webcrawlers-dashboard-assets/onboarding.php`
**Status**: Reference mockup with professional component system

### Design Flow
```
Header (Logo + Skip link)
    ↓
Title: "Connect your data"
Subtitle: "Two connected sources satisfy AC-01..."
    ↓
Progress indicator (5 steps with dots)
    ↓
Step cards (5 steps):
  • Website - done/active/error/todo
  • GSC - done/active/error/todo  
  • GA4 - done/active/error/todo
  • WordPress - done/active/error/todo
  • Conversions - done/active/error/todo
    ↓
Each step card shows:
  - Step name + badge (Connected/In progress/Action needed/Not started)
  - Description
  - Error message (if error status)
  - Action button:
    * "Manage" (if done)
    * "Continue" (if active)
    * "Retry" (if error)
    * "Connect" (if todo)
    ↓
Footer:
  - Progress: "2 of 5 connected — you can start crawling now"
  - "Go to dashboard" button
```

---

## 🎯 COMPONENT SYSTEM USED

The existing design uses these components (from `includes/components.php`):
- `dash_badge(label, tone)` - Status badge
- `dash_btn(text, options)` - Button with variants (primary, ghost, danger, etc.)
- `dash_card_open/close()` - Card layout
- `dash_filter_bar()` - Filter toolbar
- `dash_stat()` - KPI tile
- And others...

---

## 📱 CURRENT IMPLEMENTATION

### What I Created
**File**: `app/Views/onboarding/index.php`
- Custom Blade template implementation
- Uses Bootstrap classes
- Inline CSS styling
- Vanilla JavaScript handlers
- 500+ lines with all styling

### Integration Points
```
Controller: OnboardingController.php
  ↓ (queries websites, determines step status)
View: app/Views/onboarding/index.php
  ↓ (renders 5-step wizard)
Dashboard: Shows link "Start onboarding →"
Modal: create-project-modal.php (handles website creation)
  ↓ (redirects to source page after success)
```

---

## 🔄 FLOW COMPARISON

### Current Implementation Flow
```
1. User on dashboard with no websites
2. Sees welcome banner: "👋 Welcome! Get started by creating your first project. Start onboarding →"
3. Clicks link → /onboarding?redirect=dashboard
4. OnboardingController queries database for websites
5. Passes step status (active, done, todo, error) to view
6. Custom Blade view renders 5-step wizard
7. User creates website
8. Modal redirects back to source page (via wcProjectModalRedirect)
```

### Using Existing Design Flow
```
Same as above, but step 6 changes:
6. Use team's component system to render (better styling, consistent with dashboard)
```

---

## ✅ WHAT'S ALREADY WORKING

✅ Route registered: `GET /onboarding`
✅ Controller queries database: `OnboardingController::index()`
✅ Dashboard shows welcome banner with link
✅ Redirect parameter support: `/onboarding?redirect=page`
✅ Website creation modal integration
✅ Auto-redirect after success

---

## 🎨 DESIGN COMPARISON

| Aspect | My Implementation | Team Design |
|--------|-------------------|-------------|
| Component System | Custom | dash_btn, dash_badge, etc |
| Button Styling | Bootstrap | Team theme |
| Consistency | Ad-hoc | Matches dashboard perfectly |
| Maintenance | Standalone CSS | Component-based (DRY) |
| Professional | Good | Excellent |

---

## 🚀 NEXT STEPS

### Option 1: Keep Current + Improve Dashboard Button
- Keep my Blade implementation (it's working)
- Add a more prominent button in dashboard (not just link)
- Use team's button component

### Option 2: Use Team Design System
- Adapt the existing onboarding.php mockup
- Convert to CodeIgniter Blade if needed
- Or keep it as-is and link to it

### Option 3: Hybrid Approach
- Use team's component system (dash_btn, dash_badge)
- Keep the controller logic I built
- Rewrite view to use components

---

## 📍 DASHBOARD BUTTON PLACEMENT

Current: Alert banner with text link
```
<div class="alert alert-info">
    <strong>👋 Welcome!</strong> Get started by creating your first project.
    <a href="<?= site_url('onboarding') ?>">Start onboarding →</a>
</div>
```

Options:
1. **Replace with prominent button** - More visible CTA
2. **Add both alert + button** - Banner + card with button
3. **Create card section** - Better visual hierarchy
4. **Use team's dash_btn** - Consistent styling

---

## 🎁 DELIVERABLES

### Already Completed ✅
- Full onboarding wizard implementation
- 5-step flow with status tracking
- Redirect-to-source feature
- Dashboard integration
- Complete documentation

### Potential Improvements
- Switch to team's component system for consistency
- Add more prominent dashboard button
- Enhanced styling using team's design tokens

---

**Status**: Core feature working ✅  
**Recommendation**: Keep current implementation, enhance dashboard CTA

*Created: 2026-08-18*