# Website Flow Plan - Executive Summary

**Date**: 2026-08-18  
**Status**: ✅ COMPREHENSIVE PLAN COMPLETE  

---

## THE PROBLEM (3 Issues)

### 1️⃣ **Multiple Website Addition Entry Points**
Users can add websites from **6+ different places** → confusing & hard to maintain
```
GET /website
POST /api/v1/websites
POST /api/v1/websites/validate
POST /api/v1/websites/onboard
GET /settings/connections (link)
+ potentially others
```

### 2️⃣ **No Forced Onboarding**
- New users can land on any dashboard page
- Shows graceful empty state instead of guiding them
- **Should block access until ≥1 website added**

### 3️⃣ **Dashboard Incomplete**
- Current view is empty skeleton only
- Needs API integration for KPIs, pipeline, activity
- Design reference exists but not implemented

---

## THE SOLUTION (Clean & Simple)

### Phase 1: Force Onboarding for New Users
Add middleware check:
```
User Login → Check: Has websites?
   ├─ NO  → Redirect to /onboard (FORCED)
   └─ YES → Access dashboard normally
```

### Phase 2: Single Unified Entry Point
**Create new route**: `GET /onboard + POST /api/v1/onboarding/complete-website`

This becomes the **ONLY way** to add websites:
- Simple form: Domain + Max Pages + Verify Method
- Creates website, returns success
- Redirects to dashboard

### Phase 3: Complete Dashboard
**Create endpoint**: `GET /api/v1/dashboard`

Returns:
- ✅ KPIs (4 tiles): clicks, impressions, conversions, revenue
- ✅ Trend chart (28-day line graph)
- ✅ Pipeline health (opportunities, approvals, crawl %, jobs)
- ✅ Recent activity (audit log)

### Phase 4: Website Selector in Header
Add dropdown in dashboard header:
```
[Logo]  [Website Dropdown: example.com ▼]  [User Menu]
         └─ example.com (selected)
         └─ client.com
         └─ + Add Website → /onboard
```

---

## ARCHITECTURE CHANGES

### New Files/Routes

| File | Route | Purpose |
|------|-------|---------|
| `OnboardingController.php` | `GET /onboard` | Show onboarding form |
| `OnboardingApiController.php` | `POST /api/v1/onboarding/complete-website` | Process onboarding |
| `WebsiteRequiredFilter.php` | Middleware | Enforce website requirement |
| `onboarding/index.php` | View | Onboarding form template |
| `dashboard/index.php` | Update | Add KPI + pipeline rendering |
| `dashboard.js` | New JS file | Fetch & render dashboard data |

### Modified Files

| File | Change |
|------|--------|
| `DashboardModule.php` | Add website check in `initController()` |
| `Routes.php` | Add `/onboard` route, apply filter to others |
| `layout/top.php` | Add website selector dropdown |
| `dashboard/index.php` | Complete skeleton with KPI/pipeline sections |

---

## IMPLEMENTATION TIMELINE

```
Week 1 (3-4 days)
├─ Phase 1: Access control middleware
├─ Phase 2: Unified onboarding flow
└─ Phase 3: Consolidate entry points

Week 2-3 (4-5 days)
├─ Phase 4: Dashboard API & data
└─ Phase 5: Website selector component

TOTAL: ~17 days
```

---

## KEY DESIGN DECISIONS

✅ **Single entry point** (not multiple flows)
✅ **Forced onboarding** (no empty dashboards)
✅ **Website selector in header** (quick switching)
✅ **Reuse existing auth** (no new auth needed)
✅ **API-driven dashboard** (dynamic data)

---

## SECURITY

- ✅ User ownership always validated
- ✅ Website ID header validated in middleware
- ✅ Rate limiting on domain additions
- ✅ Session timeout clears selection

---

## RISKS & MITIGATIONS

| Risk | Mitigation |
|------|-----------|
| Users stuck on onboarding | Clear error messages, support email |
| Website selector confusion | Onboarding tutorial video |
| Dashboard data unavailable | Graceful fallback to empty state |
| Performance on load | Cache dashboard data, paginate activity |

---

## NEXT STEPS

1. ✅ **Review & Approve Plan** (you are here)
2. 📋 **Create Jira tickets** (5 phases, 17 tasks)
3. 🔨 **Assign developers** (recommend 1-2 people)
4. 🧪 **Implement Phase 1** (access control first)
5. 🚀 **Rollout** (staging → beta → production)

---

## DETAILED DOCUMENTATION

📄 Full plan available at: `WEBSITE_FLOW_PLAN.md`

Contains:
- Current state analysis with code references
- Detailed implementation steps for each phase
- API contracts (request/response examples)
- UI/UX flow diagram
- Complete checklist
- Testing strategy
- Data models

---

**Questions?** Review the full plan or ask for clarification on any section.

Ready to start implementation? 🚀