# SUB-4 Quick Reference
## WebCrawlers Homepage & Project Onboarding

**Status:** 📋 Planning Phase  
**Ticket:** SUB-4  
**Effort:** 9-10 weeks  
**Start Date:** TBD  

---

## 🎯 7 Main Components to Build

### 1. **Left Navigation Menu**
- Links to: Home, Audit, AI Visibility, Content, Keywords, Reports, Authority
- Active state highlighting
- Mobile hamburger menu
- 📄 Task 1.2 | Week 1-2

### 2. **Global Search Bar** ⌘K
- Search: Projects, Keywords, Domains, Tools
- Dropdown with categories
- Type-ahead suggestions
- 📄 Tasks 2.1-2.2 | Week 2-3

### 3. **AI Assistant Prompt Box**
- Suggested prompts carousel
- Routes to workflows:
  - "Audit" → Crawl
  - "Fix issues" → Issues page
  - "Discover content" → Opportunities
- 📄 Tasks 2.3-2.4 | Week 2-3

### 4. **Recommended Playbooks** (3 cards)
- Technical SEO Audit
- Fix Critical Issues
- Content Discovery
- 📄 Tasks 3.1-3.2 | Week 3-4

### 5. **Active Projects Section**
- Table/card view toggle
- Search by domain
- Filter by: Status, Score
- Sort by: Recency, A-Z, Score
- Pagination: 10/25/50 per page
- Actions: Scan, Settings, Delete
- 📄 Tasks 4.1-4.4 | Week 4-6

### 6. **"Create Project" Button**
- Opens 3-step modal wizard
- Triggers onboarding flow
- 📄 Task 4.5 | Week 6

### 7. **Project Creation Modal** (3 Steps)
**Step 1: Domain Selection**
- URL input with validation
- Checks if reachable and not duplicate
- API: POST /api/v1/websites/validate

**Step 2: Configuration**
- Max pages to crawl
- Crawl frequency
- Connect GSC, GA4, GBP
- Business info form
- API: POST /api/v1/websites/configure

**Step 3: Pixel Installation**
- Display installation code
- Copy-to-clipboard
- Verify installation
- Complete project creation
- API: POST /api/v1/websites/{id}/generate-pixel
- API: POST /api/v1/websites/{id}/verify-pixel
- API: POST /api/v1/websites/{id}/complete-onboarding

- 📄 Tasks 5.1-5.7 | Week 6-8

---

## 📊 6 Phases

| # | Phase | Weeks | Key Tasks |
|---|-------|-------|-----------|
| 1️⃣ | **Foundation** | 1-2 | Layout, Navigation, Routes |
| 2️⃣ | **Search & AI** | 2-3 | Search API, AI routing |
| 3️⃣ | **Playbooks** | 3-4 | Card design, workflow linking |
| 4️⃣ | **Projects Mgmt** | 4-6 | Listing, filtering, actions |
| 5️⃣ | **Create Modal** | 6-8 | 3-step wizard, validation, pixel |
| 6️⃣ | **Integration** | 8-10 | Jobs, testing, optimization |

---

## 📁 Files to Create

### Controllers
```
app/Controllers/DashboardController.php          (new)
app/Controllers/Api/V1/SearchController.php      (new)
app/Controllers/Api/V1/AiAssistantController.php (new)
```

### Models
```
app/Models/WebsiteModel.php  (extend existing)
```

### Views
```
app/Views/dashboard/home.php              (new)
app/Views/dashboard/components/nav.php    (new)
app/Views/dashboard/components/search.php (new)
app/Views/dashboard/components/projects.php (new)
```

### APIs to Add/Extend
```
POST   /api/v1/websites/validate
POST   /api/v1/websites/configure
POST   /api/v1/websites/{id}/generate-pixel
POST   /api/v1/websites/{id}/verify-pixel
POST   /api/v1/websites/{id}/complete-onboarding
GET    /api/v1/websites (existing, enhance)
POST   /api/v1/search
POST   /api/v1/ai/chat
```

---

## ✅ 8 Acceptance Criteria (Must Have)

1. ✅ All primary modules accessible from homepage
2. ✅ Global search finds projects, keywords, domains
3. ✅ AI assistant prompts route to workflows
4. ✅ Recommended playbooks link to features
5. ✅ Projects searchable, filterable, sortable
6. ✅ Project creation wizard validates domain
7. ✅ Pixel installation verified after creation
8. ✅ New projects queue initial crawl & sync jobs

---

## 🎨 Tech Stack

**Frontend:**
- Blade templating
- Vue.js or vanilla JS (for modal)
- Tailwind CSS for styling
- Fetch API for AJAX

**Backend:**
- CodeIgniter 4 controllers
- Query builder for DB
- Background jobs for crawls
- External APIs: GSC, GA4, GBP

**Database:**
- wc_websites table (extend)
- wc_website_settings (new, optional)
- wc_audits (existing)

---

## 🚨 Key Risks

| Risk | Impact | Mitigation |
|------|--------|-----------|
| Domain validation failures | High | Proper error handling, fallback checks |
| Integration sync complexity | High | Queue jobs, retry logic, monitoring |
| Mobile UX for modal | Medium | Early testing, responsive design |
| Performance at scale | Medium | Pagination, caching, query optimization |

---

## 📈 Success Metrics

- Homepage load time: **< 2 seconds**
- API response time: **< 500ms**
- Mobile Lighthouse score: **> 90**
- Test coverage: **> 80%**
- Zero critical bugs in QA
- All 8 acceptance criteria met

---

## 🗓️ Suggested Sprint Distribution

**Sprint 1 (Week 1-2):** Tasks 1.1-1.3 (Foundation)  
**Sprint 2 (Week 2-3):** Tasks 2.1-2.4 (Search & AI)  
**Sprint 3 (Week 3-4):** Tasks 3.1-3.2 (Playbooks)  
**Sprint 4 (Week 4-5):** Tasks 4.1-4.2 (Projects Listing)  
**Sprint 5 (Week 5-6):** Tasks 4.3-4.5 (Projects API & Create Button)  
**Sprint 6 (Week 6-7):** Tasks 5.1-5.4 (Modal Steps 1-2)  
**Sprint 7 (Week 7-8):** Tasks 5.5-5.7 (Modal Step 3 & Wiring)  
**Sprint 8 (Week 8-9):** Tasks 6.1-6.2 (Jobs & Testing)  
**Sprint 9 (Week 9-10):** Tasks 6.3-6.4 (Optimization & Docs)  

---

## 📞 Next Steps

1. **Review this plan** with team
2. **Prioritize features** if time-constrained
3. **Allocate developers** to phases
4. **Set up development environment**
5. **Begin Phase 1** (Foundation)
6. **Weekly progress reviews**

---

**Full detailed plan available in:** [SUB4_TASK_PLAN.md](SUB4_TASK_PLAN.md)