igny8/docs/PRE-LAUNCH/ITEM-4-PAGE-FLOW-UX.md

# Item 4: Page Flow and Workflow UX Improvements

**Priority:** High  
**Target:** Production Launch  
**Last Updated:** December 11, 2025

---

## Overview

Improve overall navigation, page structure, workflow clarity, and helper systems across all main user-facing areas including Setup, Workflow (Planner/Writer), Account, and Settings. This encompasses page flow standardization, helper notifications, tooltips, metrics panels, and notification systems.

---

## Current Implementation Analysis

### Main Menu Groups

**Location:** `frontend/src/layout/AppLayout.tsx` and navigation components

**Current Groups:**
1. **Setup** - Sites, Sectors, Integrations setup
2. **Workflow** - Planner (Keywords, Clusters, Ideas) and Writer (Tasks, Content, Images)
3. **Account** - Billing, Team, Profile
4. **Settings** - System settings, prompts, preferences

**Issues:**
- Inconsistent page header patterns across groups
- Some pages missing breadcrumbs or context
- Linear workflows (Planner → Writer) not clearly guided
- Cross-navigation between related pages unclear

---

### Page Header Component

**Location:** `frontend/src/components/common/PageHeader.tsx`

**Current Features:**
- Page title
- Last updated timestamp
- Site/Sector selector (can be hidden)
- Optional refresh button
- Optional badge
- Optional navigation tabs

**Strengths:**
✅ Standardized across modules  
✅ Site/sector context management  
✅ Auto-loads sectors when site changes  

**Missing:**
❌ No breadcrumbs for deeper navigation  
❌ No contextual help link  
❌ No step indicators for workflows  
❌ No quick action buttons section  

---

### Module Navigation Tabs

**Location:** `frontend/src/components/navigation/ModuleNavigationTabs.tsx`

**Current Usage:**
- Planner pages: Keywords | Clusters | Ideas | Mapping
- Writer pages: Tasks | Content | Images

**Strengths:**
✅ Consistent tab design  
✅ Active tab highlighting  
✅ Responsive layout  

**Missing:**
❌ No tab progress indicators  
❌ No disabled state for incomplete prerequisites  
❌ No tooltips explaining each tab  

---

### Helper Systems

**Current State:**
- No systematic helper notifications
- No onboarding tooltips
- No inline guidance text
- No contextual help system

**What's Needed:**
- Welcome messages for first-time page visits
- Tooltips for icons and complex actions
- Inline help text under form fields
- Step-by-step workflow banners
- Contextual "Learn more" links

---

### Metrics Display

**Current Locations:**
- Dashboard: Overview metrics
- Individual pages: Table counts, filters
- Footer: Module-specific metrics (some pages only)

**Component:** `frontend/src/components/dashboard/ModuleMetricsFooter.tsx`

**Issues:**
- Inconsistent placement (some pages have footer metrics, some don't)
- No collapsible panel option
- Metrics not updated in real-time
- No metric explanations (tooltips)

---

## Required Improvements

### A. Standardize Page Structure

#### Universal Page Template

All workflow pages should follow this structure:

```tsx
<div className="page-container">
  {/* 1. Page Header */}
  <PageHeader 
    title="Page Title"
    badge={badge}
    navigation={<ModuleNavigationTabs tabs={tabs} />}
  />
  
  {/* 2. Step Banner (if workflow page) */}
  {isWorkflowPage && <StepBanner currentStep={2} totalSteps={5} />}
  
  {/* 3. Helper Notification (first visit or contextual) */}
  {showHelper && <HelperNotification message="..." />}
  
  {/* 4. Page Actions Bar */}
  <PageActionsBar 
    primaryAction={primaryAction}
    secondaryActions={secondaryActions}
    filters={filters}
  />
  
  {/* 5. Main Content */}
  <MainContent>
    {/* Tables, forms, cards, etc. */}
  </MainContent>
  
  {/* 6. Bottom Metrics Panel (collapsible) */}
  <MetricsPanel metrics={metrics} collapsible={true} />
</div>
```

---

### B. New Components to Create

#### 1. StepBanner Component

**File:** `frontend/src/components/workflow/StepBanner.tsx` (NEW)

**Purpose:** Show current step in multi-step workflows

**Props:**
```typescript
interface StepBannerProps {
  currentStep: number;
  totalSteps: number;
  steps: Array<{
    label: string;
    href: string;
    completed: boolean;
  }>;
  onStepClick?: (stepIndex: number) => void;
}
```

**UI Design:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2 of 5: Organize into Clusters

1. Extract Keywords ✓ → 2. Cluster Keywords ● → 3. Generate Ideas → 4. Create Content → 5. Publish
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**States:**
- ✓ Completed (green, clickable)
- ● Current (blue, active)
- Pending (gray, disabled or clickable)

**Usage:**
```tsx
<StepBanner 
  currentStep={2}
  totalSteps={5}
  steps={[
    { label: 'Extract Keywords', href: '/planner/keywords', completed: true },
    { label: 'Cluster Keywords', href: '/planner/clusters', completed: false },
    { label: 'Generate Ideas', href: '/planner/ideas', completed: false },
    { label: 'Create Content', href: '/writer/tasks', completed: false },
    { label: 'Publish', href: '/writer/content', completed: false },
  ]}
/>
```

---

#### 2. HelperNotification Component

**File:** `frontend/src/components/helper/HelperNotification.tsx` (NEW)

**Purpose:** Display contextual guidance and tips

**Types:**
- **Welcome**: First-time page visit
- **Info**: General information
- **Tip**: Best practice suggestion
- **Warning**: Potential issue
- **Success**: Achievement/milestone

**Props:**
```typescript
interface HelperNotificationProps {
  type: 'welcome' | 'info' | 'tip' | 'warning' | 'success';
  title: string;
  message: string;
  actions?: Array<{
    label: string;
    href?: string;
    onClick?: () => void;
  }>;
  dismissible?: boolean;
  onDismiss?: () => void;
}
```

**UI Design:**
```
┌─────────────────────────────────────────────────┐
│ 💡 Welcome to Keywords                          │
│                                                 │
│ This is where you extract and manage SEO        │
│ keywords. Start by adding keywords manually or  │
│ importing from a CSV file.                      │
│                                                 │
│ [Import CSV] [Learn More] [Got it] [×]         │
└─────────────────────────────────────────────────┘
```

**Persistence:**
- Store dismissed state in localStorage per page
- Key: `helper_dismissed_{page_slug}`
- Option to show "Show hints again" in settings

---

#### 3. Tooltip Component Enhancement

**File:** `frontend/src/components/ui/Tooltip.tsx` (enhance existing)

**Add:**
- Keyboard accessibility (ESC to close, tab navigation)
- Delay before show (300ms hover)
- Max width constraints
- Arrow positioning
- Rich content support (not just text)

**Usage Examples:**

```tsx
{/* Simple text tooltip */}
<Tooltip content="Click to cluster all keywords">
  <button>Cluster</button>
</Tooltip>

{/* Rich content tooltip */}
<Tooltip content={
  <div>
    <strong>Clustering</strong>
    <p>Groups keywords by semantic similarity</p>
    <a href="/help/clustering">Learn more →</a>
  </div>
}>
  <InfoIcon />
</Tooltip>
```

---

#### 4. InlineGuidance Component

**File:** `frontend/src/components/helper/InlineGuidance.tsx` (NEW)

**Purpose:** Small help text under form fields

**Props:**
```typescript
interface InlineGuidanceProps {
  text: string;
  type?: 'info' | 'warning' | 'error';
  icon?: ReactNode;
}
```

**UI Design:**
```
[Input Field: Enter keyword]
ℹ️ Use lowercase, no special characters. Separate multiple keywords with commas.
```

**Usage:**
```tsx
<FormField label="Keywords">
  <input type="text" placeholder="Enter keyword" />
  <InlineGuidance 
    text="Use lowercase, no special characters. Separate multiple keywords with commas."
  />
</FormField>
```

---

#### 5. Enhanced MetricsPanel Component

**File:** `frontend/src/components/dashboard/ModuleMetricsPanel.tsx` (NEW)

**Improvements over current MetricsFooter:**
- Collapsible/expandable
- Fixed to bottom or inline at page bottom
- Real-time updates
- Tooltips explaining each metric
- Click to filter/drill-down
- Export metrics option

**Props:**
```typescript
interface MetricsPanelProps {
  title: string;
  metrics: Array<{
    label: string;
    value: string | number;
    subtitle?: string;
    icon?: ReactNode;
    color?: string;
    tooltip?: string;
    onClick?: () => void;
  }>;
  collapsible?: boolean;
  defaultCollapsed?: boolean;
  position?: 'fixed' | 'relative';
}
```

**UI Design (Expanded):**
```
┌─────────────────────────────────────────────────────────┐
│ ▼ Keyword Metrics                          [Collapse] × │
├─────────────────────────────────────────────────────────┤
│ Total: 450   │ New: 120   │ Mapped: 330   │ Vol: 125K  │
│ ℹ️ All saved │ ℹ️ Unmapped │ ℹ️ In cluster │ ℹ️ Search  │
│              │             │               │   volume   │
└─────────────────────────────────────────────────────────┘
```

**UI Design (Collapsed):**
```
▶ Keyword Metrics: 450 total, 120 new, 330 mapped
```

---

### C. Navigation Improvements

#### 1. Add Breadcrumbs

**Component:** `frontend/src/components/navigation/Breadcrumbs.tsx` (NEW)

**Usage:**
```tsx
<Breadcrumbs 
  items={[
    { label: 'Setup', href: '/setup' },
    { label: 'Sites', href: '/setup/sites' },
    { label: 'Site Settings' }, // Current page (no href)
  ]}
/>
```

**Display:**
```
Home > Setup > Sites > Site Settings
```

**Rules:**
- Show for pages 3+ levels deep
- Current page not clickable
- Auto-hide on mobile if > 3 items

---

#### 2. Cross-Navigation Links

**Add "Next Step" buttons between related pages:**

**Examples:**

| Current Page | Next Step Button | Action |
|--------------|------------------|---------|
| Keywords | "Cluster Keywords →" | Navigate to Clusters page |
| Clusters | "Generate Ideas →" | Navigate to Ideas page |
| Ideas | "Create Tasks →" | Convert ideas to tasks, navigate to Tasks |
| Tasks | "Generate Content →" | Trigger content generation |
| Content | "Generate Images →" | Navigate to Images page |

**Implementation:**
```tsx
<PageActionsBar
  primaryAction={{
    label: 'Cluster Keywords',
    icon: <ArrowRightIcon />,
    onClick: () => navigate('/planner/clusters'),
    variant: 'primary'
  }}
/>
```

---

#### 3. Workflow Progress Indicator (Global)

**Location:** Header or sidebar

**Display current workflow stage:**

```
Planner Workflow: Step 2/3
├─ Keywords ✓
├─ Clusters ● (in progress)
└─ Ideas

Writer Workflow: Not started
```

**Click to navigate to any completed or current step**

---

### D. Settings Reorganization

#### Current Problems
- Settings scattered across multiple locations
- Inconsistent categories
- Hard to find specific settings

#### Proposed Structure

**New Layout:** `frontend/src/pages/Settings/`

```
Settings/
├── index.tsx (Settings hub with cards)
├── General.tsx
├── Publishing.tsx
├── Pagination.tsx
├── Branding.tsx
├── WorkflowDefaults.tsx
├── Integrations.tsx
├── Notifications.tsx
├── Account.tsx
└── Billing.tsx (redirect to /billing)
```

**Settings Categories:**

| Category | Subcategories | What It Contains |
|----------|---------------|------------------|
| **General** | Account basics | Display name, timezone, language, date format |
| **Publishing** | WordPress settings | Connection, publishing defaults, SEO rules, auto-publish options |
| **Pagination** | List controls | Items per page for each module (keywords, clusters, ideas, etc.) |
| **Branding** | Appearance | Logo, colors, custom CSS (if applicable) |
| **Workflow Defaults** | AI settings | Default word count, tone, structure, author profile |
| **Integrations** | External services | API keys, OAuth connections, webhooks |
| **Notifications** | Alert preferences | Email alerts, in-app notifications, notification types |
| **Account & Billing** | Subscription | Plan details, usage, credits, invoices, team members |

**Settings Hub (Landing Page):**

```tsx
<SettingsHub>
  <SettingsCard 
    icon={<GeneralIcon />}
    title="General"
    description="Basic account settings and preferences"
    href="/settings/general"
  />
  <SettingsCard 
    icon={<PublishIcon />}
    title="Publishing"
    description="WordPress connection and publishing rules"
    href="/settings/publishing"
  />
  {/* ... more cards */}
</SettingsHub>
```

---

### E. Notification System

#### Notification Types

| Type | Use Case | Display | Action |
|------|----------|---------|--------|
| **Progress** | Task started, queued, processing | Blue info icon | View progress modal |
| **Success** | Task completed, export success | Green check icon | View result |
| **Failure** | API error, validation failed | Red error icon | View error details, retry |
| **Action Required** | Missing settings, incomplete setup | Orange warning icon | Navigate to fix |

#### Notification Dropdown

**Location:** Header, bell icon with badge count

**Features:**
- List notifications chronologically
- Read/unread states
- Mark all as read
- Filter by type
- Clear all button
- Links to relevant pages

**Example Notification:**
```
┌─────────────────────────────────────────────┐
│ 🔵 Content Generation Started               │
│ "Best SEO Tools 2024" - 2 minutes ago      │
│ [View Progress]                             │
├─────────────────────────────────────────────┤
│ ✅ Clustering Completed                      │
│ 45 keywords → 8 clusters - 10 min ago      │
│ [View Clusters]                             │
├─────────────────────────────────────────────┤
│ ❌ Image Generation Failed                   │
│ Insufficient credits - 1 hour ago          │
│ [Purchase Credits] [Dismiss]               │
└─────────────────────────────────────────────┘
```

#### Implementation

**Backend:**
- Create `Notification` model with account FK
- API endpoints: list, mark read, clear
- Emit notifications on key events

**Frontend:**
- `useNotifications()` hook
- `NotificationDropdown` component
- Auto-refresh every 30 seconds
- WebSocket support (future enhancement)

---

### F. Header Metrics Enhancement

**Current:** Basic stats in dashboard

**Improved:** Always-visible header metrics

**Location:** Right side of header (next to user menu)

**Display:**
```
[Icon] 3 In Progress  |  [Icon] 5 Completed  |  [Icon] 2,450 Credits  |  [Bell] 7
```

**Click to expand:**
- In Progress: Show list of running tasks
- Completed: Recent completions
- Credits: Usage breakdown, purchase link
- Bell: Notification dropdown

---

## Page-Specific Improvements

### Planner Pages

#### Keywords Page

**Add:**
- ✅ Helper: "Import keywords or add manually to start"
- ✅ Tooltip on "Cluster" button: "Group keywords by semantic similarity"
- ✅ Inline guidance on import: "CSV format: keyword, volume, difficulty"
- ✅ Next step button: "Cluster Keywords →"
- ✅ Metrics panel: Total, New, Mapped, Avg Volume

#### Clusters Page

**Add:**
- ✅ Helper: "Clusters organize keywords into topic groups"
- ✅ Step banner: Step 2/3 in Planner workflow
- ✅ Tooltip on cluster cards: Show keyword count, volume
- ✅ Next step: "Generate Ideas →"
- ✅ Metrics panel: Clusters, Avg size, Total volume

#### Ideas Page

**Add:**
- ✅ Helper: "Content ideas are generated from your clusters"
- ✅ Step banner: Step 3/3 in Planner workflow
- ✅ Content structure badge with tooltip
- ✅ Next step: "Create Tasks →" (converts to tasks)
- ✅ Metrics panel: Ideas, Cluster hubs, Word count estimates

---

### Writer Pages

#### Tasks Page

**Add:**
- ✅ Helper: "Tasks are content generation jobs queued for AI"
- ✅ Step banner: Step 1/3 in Writer workflow
- ✅ Status badges with tooltips
- ✅ Next step: "Generate Content →"
- ✅ Metrics panel: Total tasks, Queued, Completed, Total words

#### Content Page

**Add:**
- ✅ Helper: "Review and edit AI-generated content before publishing"
- ✅ Step banner: Step 2/3 in Writer workflow
- ✅ Status badges (draft/review/published)
- ✅ Next step: "Generate Images →"
- ✅ Metrics panel: Total content, Drafts, Published, Total words

#### Images Page

**Add:**
- ✅ Helper: "Generate images for your content from AI prompts"
- ✅ Step banner: Step 3/3 in Writer workflow
- ✅ Image preview on hover
- ✅ Next step: "Publish to WordPress →"
- ✅ Metrics panel: Total images, Generated, Published

---

### Automation Page

**Add:**
- ✅ Helper: "Automation runs the entire workflow automatically"
- ✅ Stage progress cards with clear metrics
- ✅ Pause/Resume/Cancel controls
- ✅ Real-time stage updates
- ✅ Estimated completion time
- ✅ Credit consumption display

---

## Implementation Plan

### Phase 1: New Components (Week 1)
1. ✅ Create StepBanner component
2. ✅ Create HelperNotification component
3. ✅ Enhance Tooltip component
4. ✅ Create InlineGuidance component
5. ✅ Create MetricsPanel component

### Phase 2: Navigation (Week 1-2)
1. ✅ Create Breadcrumbs component
2. ✅ Add cross-navigation buttons
3. ✅ Implement workflow progress indicator
4. ✅ Update ModuleNavigationTabs with tooltips

### Phase 3: Settings Reorganization (Week 2)
1. ✅ Create new Settings pages structure
2. ✅ Migrate existing settings
3. ✅ Create Settings hub landing page
4. ✅ Add category cards

### Phase 4: Notification System (Week 2-3)
1. ✅ Create Notification model (backend)
2. ✅ Create notification endpoints
3. ✅ Create NotificationDropdown component
4. ✅ Integrate with existing workflows
5. ✅ Add bell icon with badge to header

### Phase 5: Page Updates (Week 3)
1. ✅ Update all Planner pages with new components
2. ✅ Update all Writer pages with new components
3. ✅ Update Automation page
4. ✅ Add helpers, tooltips, metrics to each page

---

## Success Metrics

- ✅ All workflow pages have step banners
- ✅ All pages have helper notifications on first visit
- ✅ All icons and actions have tooltips
- ✅ All form fields have inline guidance
- ✅ Settings are organized and easy to find
- ✅ Users receive notifications for all key events
- ✅ Cross-navigation reduces clicks to complete workflows
- ✅ Metrics panels show real-time data
- ✅ User feedback indicates clearer navigation

---

## Related Files Reference

### Components (NEW)
- `frontend/src/components/workflow/StepBanner.tsx`
- `frontend/src/components/helper/HelperNotification.tsx`
- `frontend/src/components/helper/InlineGuidance.tsx`
- `frontend/src/components/navigation/Breadcrumbs.tsx`
- `frontend/src/components/dashboard/MetricsPanel.tsx`
- `frontend/src/components/notifications/NotificationDropdown.tsx`

### Components (Enhance)
- `frontend/src/components/common/PageHeader.tsx`
- `frontend/src/components/navigation/ModuleNavigationTabs.tsx`
- `frontend/src/components/ui/Tooltip.tsx`

### Pages (Update)
- All `frontend/src/pages/Planner/*.tsx`
- All `frontend/src/pages/Writer/*.tsx`
- `frontend/src/pages/Automation/*.tsx`
- `frontend/src/pages/Settings/*.tsx` (reorganize)

### Backend (NEW)
- `backend/igny8_core/modules/system/models.py` - Add Notification model
- `backend/igny8_core/modules/system/views.py` - Notification endpoints

---

## Notes

- Helper notifications should be non-intrusive and dismissible
- Tooltips should be brief (2-3 sentences max)
- Metrics should update in real-time or near-real-time
- Settings should be searchable (future enhancement)
- Consider onboarding tour for new users (future phase)
- All guidance text should be editable by admin (future enhancement)