igny8/refactor-plan/FINAL_REFACTOR_TASKS.md

# Final Refactor Tasks - Account/Plan Validation & Design Consistency

**Status:** Planning Phase  
**Last Updated:** 2025-01-27  
**Objective:** Enforce account/plan requirements at authentication level, fix design inconsistencies in Sites pages, and add welcome/guide screen for new user onboarding.

---

## 📋 Implementation Tasks

### 1. Remove Account Fallback - Fail Authentication

| Location | Current State | Required Changes | Priority |
|----------|---------------|------------------|----------|
| `backend/igny8_core/auth/views.py:912-953` | Login allows `account = None` (line 934) | Add validation: if `user.account is None`, return error: `"No account exists for this user. Please contact support."` with status 403 | **HIGH** |
| `backend/igny8_core/auth/urls.py:76-89` | Same issue in legacy LoginView | Same validation | **HIGH** |
| `frontend/src/store/authStore.ts:48-89` | No account validation after login | After login success, check `user.account` - if null, throw error and prevent login | **HIGH** |
| `frontend/src/components/auth/SignInForm.tsx:30` | No account validation | Display error message if account is missing | **HIGH** |

**Implementation Details:**
- After line 934 in `views.py`, add: `if not account: return error_response(error='No account exists for this user', status_code=403)`
- After line 74 in `authStore.ts`, add: `if (!user.account) { throw new Error('No account exists') }`

---

### 2. Remove Plan Fallback - Fail Authentication & Redirect

| Location | Current State | Required Changes | Priority |
|----------|---------------|------------------|----------|
| `backend/igny8_core/auth/views.py:912-953` | No plan validation | Add validation: if `user.account.plan is None`, return error: `"No plan subscribed. Please subscribe to a plan."` with status 403 and error code `NO_PLAN` | **HIGH** |
| `frontend/src/store/authStore.ts:48-89` | No plan validation | After login, check `user.account?.plan` - if null, logout and redirect to `https://igny8.com/pricing` | **HIGH** |
| `frontend/src/components/auth/SignInForm.tsx:30-36` | No plan validation | Catch `NO_PLAN` error and redirect to pricing page | **HIGH** |

**Implementation Details:**
- After account check in `views.py`, add: `if not account.plan: return error_response(error='No plan subscribed', error_code='NO_PLAN', status_code=403)`
- After account check in `authStore.ts`, add: `if (!user.account.plan) { logout(); window.location.href = 'https://igny8.com/pricing'; throw new Error('No plan subscribed') }`

---

### 3. Account Settings - Specific Error Handling

| Location | Current State | Required Changes | Priority |
|----------|---------------|------------------|----------|
| `frontend/src/services/api.ts:1479-1485` | No try-catch, throws generic error | Add try-catch with specific error types: `ACCOUNT_SETTINGS_API_ERROR`, `ACCOUNT_SETTINGS_NOT_FOUND`, `ACCOUNT_SETTINGS_VALIDATION_ERROR` | **MEDIUM** |
| Components using `fetchAccountSettings()` | Generic error handling | Display specific error messages based on error type | **MEDIUM** |

**Implementation Details:**
- Wrap `fetchAccountSettings()` in try-catch
- Return structured error with type
- Update components to display specific error messages

---

### 4. User/Account Access - Component Null Handling Review

| Location | Current State | Required Changes | Priority |
|----------|---------------|------------------|----------|
| All components using `user.account` | Uses optional chaining `user?.account?.slug` but no enforcement | Audit all components, add validation: if `user.account` is null during session, logout user immediately | **HIGH** |
| `frontend/src/components/common/SiteAndSectorSelector.tsx:50` | Uses `user?.account?.id` | Add validation check | **MEDIUM** |
| `frontend/src/layout/AppSidebar.tsx:45` | Uses `user?.account?.slug` | Add validation check | **MEDIUM** |
| `frontend/src/components/header/SiteSwitcher.tsx:93` | Uses `user?.account?.id` | Add validation check | **MEDIUM** |
| `frontend/src/store/authStore.ts:192-217` | `refreshUser()` doesn't validate account | After refresh, validate `user.account` - if null, logout | **HIGH** |

**Implementation Details:**
- Create utility function to validate user account/plan
- Add validation in `refreshUser()` method
- Add validation checks in components that access `user.account`

---

### 5. Site/Sector Null Handling Review

| Location | Current State | Required Changes | Priority |
|----------|---------------|------------------|----------|
| Components using `activeSite` | Can be `null`, some components may not handle | Audit all components, ensure null checks before accessing `activeSite` properties | **MEDIUM** |
| Components using `activeSector` | Can be `null`, some components may not handle | Audit all components, ensure null checks before accessing `activeSector` properties | **MEDIUM** |
| `frontend/src/pages/Planner/Dashboard.tsx:84-88` | Uses `activeSector?.id` and `activeSite?.id` | Already has optional chaining - verify all usages | **LOW** |
| `frontend/src/services/api.ts:453-466` | Uses `getActiveSiteId()` and `getActiveSectorId()` | Already has null checks - verify all usages | **LOW** |

**Implementation Details:**
- Audit all components using `activeSite` and `activeSector`
- Ensure all components handle null cases gracefully
- Add null checks where missing

---

### 6. Optimize Missing Fallbacks - Session Validation

| Location | Current State | Required Changes | Priority |
|----------|---------------|------------------|----------|
| `frontend/src/components/auth/ProtectedRoute.tsx:15-95` | Only checks `isAuthenticated` | Add validation: check `user.account` and `user.account.plan` - if null, logout and redirect | **HIGH** |
| `frontend/src/store/authStore.ts:192-217` | `refreshUser()` doesn't validate | After refresh, validate account/plan - if null, logout immediately | **HIGH** |
| `frontend/src/App.tsx` | No global validation | Add useEffect hook to validate account/plan on route changes | **HIGH** |
| `backend/igny8_core/auth/middleware.py:24-121` | Sets `request.account = None` on error | Should return 403 if account is required but missing | **MEDIUM** |
| `backend/igny8_core/api/authentication.py:21-73` | Sets `account = None` if not found | Should fail authentication if account is required | **MEDIUM** |

**Implementation Details:**
- Add validation function to check account/plan
- Add validation in `ProtectedRoute` before returning children
- Add global validation in `App.tsx` useEffect
- Update middleware to fail on missing account

---

### 7. Design Consistency - Sites Pages

**Issue:** Sites pages use completely different layouts, components, and colors compared to the standard app design used in Planner, Writer, Thinker, and Automation dashboards.

| Location | Current State | Required Changes | Priority |
|----------|---------------|------------------|----------|
| `frontend/src/pages/Sites/Dashboard.tsx` | Custom header, raw `Card` components | Replace with `PageHeader` and `ComponentCard` | **HIGH** |
| `frontend/src/pages/Sites/List.tsx` | Custom styling, different layout | Use standard components and spacing patterns | **HIGH** |
| `frontend/src/pages/Sites/Builder/*` | Different components and colors | Use standard design system components | **HIGH** |
| `frontend/src/pages/Sites/Settings.tsx` | Custom layout | Use standard components | **MEDIUM** |
| `frontend/src/pages/Sites/Content.tsx` | Custom styling | Use standard components | **MEDIUM** |
| `frontend/src/pages/Sites/PageManager.tsx` | Custom layout | Use standard components | **MEDIUM** |
| `frontend/src/pages/Sites/SyncDashboard.tsx` | Custom styling | Use standard components | **MEDIUM** |
| `frontend/src/pages/Sites/DeploymentPanel.tsx` | Custom styling | Use standard components | **MEDIUM** |

**Design Consistency Details:**

| Issue | Reference (Planner/Writer) | Sites Pages (Broken) | Fix Required |
|-------|---------------------------|----------------------|-------------|
| **Page Headers** | Uses `PageHeader` component with `title`, `lastUpdated`, `showRefresh` | Custom `<h1>` and manual layout | Replace with `PageHeader` |
| **Info Cards** | Uses `ComponentCard` with `title` and `desc` props | Raw `Card` with custom styling | Replace with `ComponentCard` |
| **Metric Cards** | Uses `EnhancedMetricCard` with consistent styling | Custom stat cards with different styling | Replace with `EnhancedMetricCard` |
| **Spacing** | Uses `space-y-6` for consistent vertical spacing | Mixed spacing (`mb-6`, `mb-4`, etc.) | Standardize to `space-y-6` |
| **Colors** | Uses CSS variables (`var(--color-primary)`) | Hardcoded colors (`text-gray-900`, `bg-blue-500`) | Replace with CSS variables |
| **Loading States** | Consistent loading spinner pattern | Different loading patterns | Standardize loading states |
| **Button Styles** | Standard `Button` component with variants | Mixed button styles | Use standard `Button` component |
| **Layout Patterns** | Consistent grid layouts (`grid-cols-1 md:grid-cols-2 lg:grid-cols-4`) | Inconsistent grid patterns | Standardize grid layouts |

**Implementation Details:**
- Replace all custom headers with `PageHeader` component
- Replace raw `Card` components with `ComponentCard` where appropriate
- Replace custom metric cards with `EnhancedMetricCard`
- Standardize spacing to `space-y-6` pattern
- Replace hardcoded colors with CSS variables
- Standardize loading states
- Use standard `Button` component consistently
- Standardize grid layout patterns

---

### 8. Welcome/Guide Screen - Workflow Explainer for New Users

**Issue:** The Dashboard home page (`frontend/src/pages/Dashboard/Home.tsx`) lacks onboarding guidance for new users. After signup, users see generic metrics without understanding the complete workflow or next steps.

| Location | Current State | Required Changes | Priority |
|----------|---------------|------------------|----------|
| `frontend/src/pages/Dashboard/Home.tsx` | ✅ Inline `WorkflowGuide` rendered above dashboard content | Keep guide responsive, continue iterating on progress tracking & backend dismissal | **HIGH** |
| `frontend/src/components/onboarding/WorkflowGuide.tsx` | ✅ Component created with Build vs Integrate flows and CTA grid | Add advanced progress logic + backend persistence once API is ready | **HIGH** |
| `frontend/src/components/header/AppHeader.tsx` | ✅ Orange "Show/Hide Guide" button added next to metrics | Ensure button state syncs with backend dismissal when implemented | **HIGH** |
| `frontend/src/store/onboardingStore.ts` | ✅ Store created with dismiss + toggle actions (persisted) | Wire to backend `guide_dismissed` field once available | **MEDIUM** |
| Backend - User model/settings | No field for guide dismissal | Add `guide_dismissed` or `show_workflow_guide` field | **MEDIUM** |

**Workflow Guide Features:**

| Feature | Description | Implementation Details |
|---------|-------------|----------------------|
| **Inline Page Display** | Shows directly in Home page content area (not modal/overlay) | Appears at top of page, pushes dashboard content below |
| **Dismissible** | User can hide it with "Don't show this again" checkbox | Store preference in `localStorage` + backend |
| **Re-open Button** | Orange-colored button in top right header | Text: "Show Guide" or "Workflow Guide" - stands out with orange color scheme |
| **Progress Tracking** | Show completed steps (✓) vs pending (○) | Track via `WorkflowState`, sites, clusters, content, published posts |
| **Contextual CTAs** | "Start Building Site", "Explore Planner", etc. based on progress | Conditional rendering based on user state |

**Workflow Flow Structure:**

| Main Choice | Sub-Option 1 | Sub-Option 2 | Description |
|-------------|--------------|-------------|-------------|
| **Build New Site** | WordPress Self-Hosted Site | IGNY8-Powered IGNY8-Hosted Site | User wants to create a new site from scratch |
| **Integrate Existing Site** | Integrate WordPress/Shopify | Custom Site | User wants to connect an existing site |

**Button Specifications:**

| Property | Value | Notes |
|----------|-------|-------|
| **Location** | Top right corner of header | Next to user profile/notifications |
| **Color** | Orange color scheme | Distinct from primary/secondary colors |
| **Text** | "Show Guide" or "Workflow Guide" | Clear, action-oriented label |
| **Behavior** | Toggles guide visibility | Shows/hides inline guide component |
| **Icon** | Book/Guide icon (optional) | Visual indicator |

**Implementation Details:**
- Create `<WorkflowGuide>` component with inline display (not modal)
- Include complete workflow visualization from `COMPLETE_USER_WORKFLOW_GUIDE.md`
- Track user progress: check if user has sites, clusters, content, published posts
- Show progress percentage (0% → 100%) based on completion
- Add "Don't show again" checkbox at bottom
- Store dismissal preference in `useOnboardingStore` and backend
- Add orange "Show Guide" button in `AppHeader` or header component
- Guide appears at top of Home page, dashboard content appears below it
- Use standard `Card`, `Button`, `Badge` components for consistency
- Make responsive for mobile/tablet views

---

### 9. Sidebar Restructuring - Simplified Navigation with In-Page Tabs

**Issue:** Current sidebar has too many dropdown menus, making navigation cluttered. Dashboard pages are redundant when metrics can be shown on table pages. Need clearer organization: Setup → Workflow → Settings.

| Location | Current State | Required Changes | Priority |
|----------|---------------|------------------|----------|
| `frontend/src/layout/AppSidebar.tsx` | Multiple dropdown menus, dashboard sub-items | Restructure to single items with in-page navigation | **HIGH** |
| `frontend/src/pages/Planner/*` | Separate dashboard page | Remove dashboard, add in-page navigation tabs | **HIGH** |
| `frontend/src/pages/Writer/*` | Separate dashboard page | Remove dashboard, add in-page navigation tabs | **HIGH** |
| `frontend/src/pages/Linker/*` | Separate dashboard page | Remove dashboard, add in-page navigation tabs | **HIGH** |
| `frontend/src/pages/Optimizer/*` | Separate dashboard page | Remove dashboard, add in-page navigation tabs | **HIGH** |
| `frontend/src/pages/Thinker/*` | Separate dashboard page | Remove dashboard, add in-page navigation tabs | **HIGH** |
| `frontend/src/pages/Automation/*` | Separate dashboard page | Remove dashboard, add in-page navigation tabs | **HIGH** |
| `frontend/src/pages/Setup/IndustriesSectorsKeywords.tsx` | Does not exist | Create merged page for Industry/Sectors/Keywords | **HIGH** |
| `frontend/src/components/navigation/ModuleNavigationTabs.tsx` | Does not exist | Create reusable tab navigation component | **HIGH** |
| `frontend/src/components/dashboard/ModuleMetricsFooter.tsx` | Does not exist | Create compact metrics footer for table pages | **MEDIUM** |

**New Sidebar Structure:**

| Section | Menu Items | Type | Default Route | Notes |
|---------|------------|------|---------------|-------|
| **(No Section)** | Dashboard | Single | `/` | Standalone, no section header |
| **SETUP** | Industry/Sectors/Keywords | Single | `/setup/industries-sectors-keywords` | Merged page: Industry/Sectors + Keyword Opportunities, saved to user account |
| | Sites | Single | `/sites` | Submenus shown as in-page navigation |
| | Automation | Single | `/automation/rules` | Submenus shown as in-page navigation |
| | Thinker | Single | `/thinker/prompts` | Submenus shown as in-page navigation |
| **WORKFLOW** | Planner | Single | `/planner/keywords` | Submenus shown as in-page navigation |
| | Writer | Single | `/writer/content` | Submenus shown as in-page navigation |
| | Linker | Single | `/linker/content` | Submenus shown as in-page navigation |
| | Optimizer | Single | `/optimizer/content` | Submenus shown as in-page navigation |
| **SETTINGS** | Settings | Dropdown | `/settings` | Keep dropdown (General, Plans, Integration, Publishing, Import/Export) |
| | Billing | Dropdown | `/billing/credits` | Keep dropdown (Credits, Transactions, Usage) |
| | Help & Documentation | Single | `/help` | No dropdown |

**In-Page Navigation Details:**

| Module | In-Page Navigation Tabs | Tab Routes |
|--------|-------------------------|------------|
| **Industry/Sectors/Keywords** | Industry/Sectors \| Keyword Opportunities | Single page with tabs/sections |
| **Sites** | All Sites \| Create Site \| Blueprints \| Sync Dashboard \| Deployment Panel | `/sites`, `/sites/builder`, `/sites/blueprints`, `/sites/sync`, `/sites/deploy` |
| **Automation** | Rules \| Tasks | `/automation/rules`, `/automation/tasks` |
| **Thinker** | Prompts \| Author Profiles \| Strategies \| Image Testing | `/thinker/prompts`, `/thinker/author-profiles`, `/thinker/strategies`, `/thinker/image-testing` |
| **Planner** | Keywords \| Clusters \| Ideas | `/planner/keywords`, `/planner/clusters`, `/planner/ideas` |
| **Writer** | Tasks \| Content \| Images \| Published | `/writer/tasks`, `/writer/content`, `/writer/images`, `/writer/published` |
| **Linker** | Content | `/linker/content` (single item, no tabs needed) |
| **Optimizer** | Content | `/optimizer/content` (single item, no tabs needed) |

**Industry/Sectors/Keywords Integration:**

| Feature | Description | Implementation |
|---------|-------------|----------------|
| **Purpose** | Pre-setup page before creating sites | User selects industry, sectors, and keywords before site creation |
| **Data Storage** | Saved to user account (not site-specific) | Available when creating sites |
| **Layout** | Tabbed interface or sections | Industry/Sectors tab + Keyword Opportunities tab |
| **Site Builder Integration** | Load pre-selected data | Site builder loads industries/sectors from user account |
| **Site Settings** | Show only pre-selected options | Site settings show only industries/sectors user intended to use |

**Implementation Details:**
- Remove all "Dashboard" sub-items from sidebar
- Convert dropdown menus to single items with in-page tab navigation
- Create `ModuleNavigationTabs` component for reusable tab navigation
- Create `ModuleMetricsFooter` component for compact metrics on table pages
- Create merged `IndustriesSectorsKeywords` page combining Industry/Sectors and Keyword Opportunities
- Update Site Builder to load industries/sectors from user account (not site-specific)
- Update Site Settings to show only pre-selected industries/sectors
- Add metrics footer to all Planner, Writer, Linker, Optimizer table pages
- Remove separate dashboard routes for Planner, Writer, Linker, Optimizer, Thinker, Automation
- Update routing to remove dashboard paths from sidebar navigation

---

## 📊 Priority Summary

| Priority | Count | Tasks |
|----------|-------|-------|
| **HIGH** | 27 | Backend account/plan validation, Frontend login validation, Session validation, Design consistency for Sites pages, Welcome/Guide screen component, Guide button, Sidebar restructuring, In-page navigation, Dashboard removal, Industry/Sectors/Keywords merge |
| **MEDIUM** | 13 | Account settings errors, Component null checks, Design consistency for remaining Sites pages, Guide persistence/store, Module metrics footer |
| **LOW** | 2 | Site/Sector null handling (mostly handled) |

**Total Tasks:** 42

---

## 🔄 Implementation Phases

### Phase 1: Backend Authentication (HIGH Priority)
1. Add account validation to login endpoints
2. Add plan validation to login endpoints
3. Update middleware to fail on missing account

### Phase 2: Frontend Authentication (HIGH Priority)
1. Validate account after login
2. Validate plan after login
3. Handle NO_PLAN error with redirect
4. Add validation to ProtectedRoute
5. Add global session validation in App.tsx

### Phase 3: Component Null Handling (HIGH Priority)
1. Audit all components using `user.account`
2. Add validation to `refreshUser()`
3. Add validation checks in components

### Phase 4: Design Consistency - Core Sites Pages (HIGH Priority)

**Design System Requirements:**
- **Colors**: Use CSS variables `var(--color-primary)`, `var(--color-success)`, `var(--color-warning)`, `var(--color-purple)` and their `-dark` variants
- **Gradients**: Use `from-[var(--color-primary)] to-[var(--color-primary-dark)]` pattern for icon backgrounds (matching Planner/Writer dashboards)
- **Icons**: Import from `../../icons` (not lucide-react), use same icon patterns as Planner/Writer/Thinker/Automation/Dashboard
- **Components**: Use standard `Button`, `Card`, `Badge`, `PageHeader`, `EnhancedMetricCard` from design system
- **Layout**: Use same spacing (`p-6`, `gap-4`, `rounded-xl`), border-radius, shadow patterns as Dashboard/Planner/Writer pages
- **Buttons**: Use standard Button component with `variant="primary"`, `variant="outline"` etc.
- **Cards**: Use standard Card component or EnhancedMetricCard for metrics (matching Dashboard/Planner patterns)
- **Badges**: Use standard Badge component with color variants matching design system
- **Stat Cards**: Use gradient icon backgrounds like Planner Dashboard: `bg-gradient-to-br from-[var(--color-primary)] to-[var(--color-primary-dark)]`
- **Hover States**: Use `hover:border-[var(--color-primary)]` pattern for interactive cards

**Completed:**
1. ✅ Refactor Sites Dashboard - Replaced lucide-react icons, using EnhancedMetricCard, standard colors/gradients, PageHeader component (matches Planner dashboard patterns)
2. ✅ Refactor Sites List - Converted to `TablePageTemplate`, added table/grid toggle, mirrored Planner/Writer table styling, moved actions into standard header buttons, removed legacy site/sector selectors

**Remaining:**
3. Refactor Sites Builder pages - Apply same design system patterns

### Phase 5: Design Consistency - Remaining Sites Pages (MEDIUM Priority)
1. Refactor Sites Settings
2. Refactor Sites Content
3. Refactor Sites PageManager
4. Refactor Sites SyncDashboard
5. Refactor Sites DeploymentPanel

### Phase 6: Account Settings & Site/Sector Handling (MEDIUM/LOW Priority)
1. Add specific error handling for account settings
2. Audit and fix site/sector null handling

### Phase 7: Welcome/Guide Screen & Onboarding (HIGH Priority)
**Completed**
1. ✅ Create WorkflowGuide component (inline, not modal)
2. ✅ Create onboarding store for state management
3. ✅ Add orange "Show Guide" button in header
4. ✅ Implement flow structure (Build New Site vs Integrate Existing Site)
5. ✅ Integrate guide at top of Home page (pushes dashboard below)
6. ✅ Initial responsive pass on desktop/tablet/mobile

**Next**
7. Add backend dismissal field + persist state
8. Expand progress tracking logic (planner/writer milestones)
9. Cross-device QA once backend wiring is complete

### Phase 8: Sidebar Restructuring & Navigation (HIGH Priority)
1. Restructure sidebar: Dashboard (standalone) → SETUP → WORKFLOW → SETTINGS
2. Remove all dashboard sub-items from sidebar
3. Convert dropdown menus to single items (Planner, Writer, Linker, Optimizer, Thinker, Automation, Sites)
4. Create ModuleNavigationTabs component for in-page tab navigation
5. Create merged IndustriesSectorsKeywords page (Industry/Sectors + Keyword Opportunities)
6. Update Site Builder to load industries/sectors from user account
7. Update Site Settings to show only pre-selected industries/sectors
8. Add in-page navigation tabs to all module pages
9. Remove separate dashboard routes for Planner, Writer, Linker, Optimizer, Thinker, Automation
10. Create ModuleMetricsFooter component for compact metrics on table pages
11. Add metrics footer to all table pages (Planner, Writer, Linker, Optimizer)
12. Test navigation flow and responsive design

---

## ✅ Success Criteria

1. **Authentication:** Users without account or plan cannot sign in
2. **Session Validation:** Users with missing account/plan are logged out automatically
3. **Design Consistency:** All Sites pages match the standard app design
4. **Error Handling:** Specific, actionable error messages for all failure cases
5. **Null Safety:** All components handle null cases gracefully
6. **Onboarding:** New users see an inline workflow guide on first login with clear flow options (Build New Site vs Integrate Existing Site) and progress tracking
7. **Guide Access:** Users can dismiss the guide and re-open it via an orange "Show Guide" button in the header
8. **Sidebar Navigation:** Sidebar simplified to 12 items with clear Setup → Workflow → Settings organization
9. **In-Page Navigation:** All modules use in-page tab navigation instead of sidebar dropdowns
10. **Pre-Setup Data:** Industry/Sectors/Keywords saved to user account and available during site creation
11. **Dashboard Removal:** All module dashboards removed, metrics shown as compact footer on table pages

---

*This plan ensures strict account/plan validation and design consistency across the entire application.*