Files

IGNY8 VPS (Salman) d9dbb1e4b8 DOCS

2025-12-15 03:04:06 +00:00

36 KiB

Raw Blame History

Implementation Audit & Action Plan

Pre-Launch Items 1 & 4: Status Modules + Page Flow UX

Date: December 15, 2025
Status: Complete System Audit
Purpose: Identify current implementation state and define exact changes needed

UX Components Audit
Page Structure Audit
Module-by-Module Implementation Status

UX Components Audit

Components Required by ITEM-4 but Missing

Component	Status	Purpose	Priority
StepBanner	🔴 Missing	Show workflow step progress (Step 2/5)	High
HelperNotification	🔴 Missing	Contextual guidance messages	High
InlineGuidance	🔴 Missing	Help text under form fields	Medium
Breadcrumbs	🔴 Missing	Navigation breadcrumb trail	Medium
MetricsPanel	🔴 Missing	Collapsible bottom metrics panel	High
NotificationDropdown	🔴 Missing	Bell icon notifications	Medium

Existing Components (Good)

Component	Status	Location	Notes
PageHeader	✅ Exists	`frontend/src/components/common/PageHeader.tsx`	Well-implemented, standardized
ModuleNavigationTabs	✅ Exists	`frontend/src/components/navigation/ModuleNavigationTabs.tsx`	Works well, needs tooltips
Tooltip	✅ Exists	`frontend/src/components/ui/tooltip/Tooltip.tsx`	Basic implementation, needs enhancement
ProgressModal	✅ Exists	`frontend/src/components/common/ProgressModal.tsx`	Needs refactoring

New Components to Create

1. StepBanner Component

Purpose: Display workflow step progress (e.g., "Step 2 of 5: Cluster Keywords")

Location: frontend/src/components/workflow/StepBanner.tsx (NEW)

Props:

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

Visual:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2 of 5: Organize into Clusters

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

Usage:

<StepBanner 
  currentStep={2}
  totalSteps={5}
  steps={[
    { label: 'Extract Keywords', href: '/planner/keywords', completed: true },
    { label: 'Cluster Keywords', href: '/planner/clusters', completed: false },
    // ...
  ]}
/>

2. HelperNotification Component

Purpose: Show contextual guidance (welcome, tips, warnings)

Location: frontend/src/components/helper/HelperNotification.tsx (NEW)

Props:

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

Visual:

┌─────────────────────────────────────────────────┐
│ 💡 Welcome to Keywords                          │
│                                                 │
│ Extract and manage SEO keywords. Start by       │
│ adding keywords manually or importing CSV.      │
│                                                 │
│ [Import CSV] [Learn More] [Got it] [×]         │
└─────────────────────────────────────────────────┘

Persistence: Store dismissed state in localStorage per page

3. InlineGuidance Component

Purpose: Small help text under form fields

Location: frontend/src/components/helper/InlineGuidance.tsx (NEW)

Props:

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

Visual:

[Input Field: Enter keyword]
ℹ️ Use lowercase, no special characters. Separate with commas.

4. Breadcrumbs Component

Purpose: Navigation breadcrumb trail

Location: frontend/src/components/navigation/Breadcrumbs.tsx (NEW)

Props:

interface BreadcrumbsProps {
  items: Array<{
    label: string;
    href?: string; // No href = current page
  }>;
}

Visual:

Home > Setup > Sites > Site Settings

5. MetricsPanel Component

Purpose: Collapsible metrics panel at page bottom

Location: frontend/src/components/dashboard/MetricsPanel.tsx (NEW)

Props:

interface MetricsPanelProps {
  title: string;
  metrics: Array<{
    label: string;
    value: string | number;
    subtitle?: string;
    icon?: ReactNode;
    tooltip?: string;
    onClick?: () => void;
  }>;
  collapsible?: boolean;
  defaultCollapsed?: boolean;
}

Visual (Expanded):

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

6. NotificationDropdown Component

Purpose: Bell icon with notification list

Location: frontend/src/components/notifications/NotificationDropdown.tsx (NEW)

Backend Required: Notification model with account FK

Props:

interface NotificationDropdownProps {
  notifications: Notification[];
  unreadCount: number;
  onMarkRead: (id: number) => void;
  onClearAll: () => void;
}

Current Location: frontend/src/components/ui/tooltip/Tooltip.tsx

Current Implementation: Basic hover tooltip with portal rendering

Required Enhancements:

Enhancement	Current	Required
Keyboard accessibility	❌ No ESC handler	✅ ESC to close, tab navigation
Hover delay	❌ Immediate show	✅ 300ms delay before show
Max width	❌ Whitespace nowrap	✅ Max-width with wrapping
Rich content	❌ Text only	✅ Support ReactNode content
Arrow positioning	✅ Has arrow	✅ Keep current (good)

Example Usage (Enhanced):

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

Page Structure Audit

Current Page Structure (Planner/Writer Pages)

Example: Keywords.tsx

<div>
  <PageHeader 
    title="Keywords"
    badge={{ icon: <KeyIcon />, color: 'blue' }}
    navigation={<ModuleNavigationTabs tabs={tabs} />}
  />
  
  {/* Actions bar */}
  <div className="actions">
    <Button>Import</Button>
    <Button>Add</Button>
  </div>
  
  {/* Main content - table */}
  <Table data={keywords} />
  
  {/* No metrics panel */}
</div>

Required Page Structure (Standardized)

All workflow pages should follow:

<div className="page-container">
  {/* 1. Page Header (EXISTS) */}
  <PageHeader 
    title="Page Title"
    badge={badge}
    navigation={<ModuleNavigationTabs tabs={tabs} />}
  />
  
  {/* 2. Step Banner (MISSING - needs creation) */}
  {isWorkflowPage && <StepBanner currentStep={2} totalSteps={5} />}
  
  {/* 3. Helper Notification (MISSING - needs creation) */}
  {showHelper && <HelperNotification type="welcome" message="..." />}
  
  {/* 4. Breadcrumbs (MISSING - needs creation) */}
  {showBreadcrumbs && <Breadcrumbs items={breadcrumbs} />}
  
  {/* 5. Page Actions Bar (EXISTS, needs standardization) */}
  <PageActionsBar 
    primaryAction={primaryAction}
    secondaryActions={secondaryActions}
    filters={filters}
  />
  
  {/* 6. Main Content (EXISTS) */}
  <MainContent>
    {/* Tables, forms, cards */}
  </MainContent>
  
  {/* 7. Metrics Panel (MISSING - needs creation) */}
  <MetricsPanel metrics={metrics} collapsible={true} />
</div>

Page Header Usage Analysis

Current Status: ✅ PageHeader is used on all major pages

Module	Page	Has PageHeader	Has Navigation	Missing Elements
Planner	Keywords	✅ Yes	✅ Yes	StepBanner, Helper, Metrics
Planner	Clusters	✅ Yes	✅ Yes	StepBanner, Helper, Metrics
Planner	Ideas	✅ Yes	✅ Yes	StepBanner, Helper, Metrics
Writer	Tasks	✅ Yes	✅ Yes	StepBanner, Helper, Metrics
Writer	Content	✅ Yes	✅ Yes	StepBanner, Helper, Metrics
Writer	Images	✅ Yes	✅ Yes	StepBanner, Helper, Metrics
Automation	Automation	✅ Yes	❌ No tabs	Helper, stage progress fixes

Module-by-Module Implementation Status

PLANNER MODULE

Keywords Page

Location: frontend/src/pages/Planner/Keywords.tsx

Feature	Status	Current	Required	Action
PageHeader	✅	Has title, badge, tabs	✅ Good	None
StepBanner	❌	None	Show "Step 1/3: Extract Keywords"	Add component
Helper	❌	None	"Import keywords or add manually"	Add welcome message
Progress Modal	✅	useProgressModal for clustering	Fix message counts	Update backend tracker
Metrics Panel	❌	None	Total, New, Mapped, Avg Volume	Add component
Tooltips	❌	None	"Cluster" button, import icon	Add tooltips
Next Step Button	❌	None	"Cluster Keywords →"	Add button to actions

Required Changes:

Add StepBanner showing step 1/3 in Planner workflow
Add HelperNotification on first visit: "Import keywords or add manually to start"
Add Tooltip on "Cluster" button: "Group keywords by semantic similarity"
Add MetricsPanel at bottom with: Total keywords, New (unmapped), Mapped, Avg volume
Add "Next Step" button: "Cluster Keywords →" navigating to /planner/clusters
Backend: Update clustering progress to include keyword counts in details

Clusters Page

Location: frontend/src/pages/Planner/Clusters.tsx

Feature	Status	Current	Required	Action
PageHeader	✅	Has title, badge, tabs	✅ Good	None
StepBanner	❌	None	Show "Step 2/3: Organize Clusters"	Add component
Helper	❌	None	"Clusters organize keywords into topic groups"	Add welcome message
Progress Modal	❌	No generation function	N/A (future feature)	None
Metrics Panel	❌	None	Total clusters, Avg size, Total volume	Add component
Tooltips	❌	None	Cluster cards, action buttons	Add tooltips
Next Step Button	❌	None	"Generate Ideas →"	Add button to actions

Required Changes:

Add StepBanner showing step 2/3 in Planner workflow
Add HelperNotification: "Clusters organize keywords into topic groups"
Add Tooltip on cluster cards showing keyword count and volume
Add MetricsPanel: Total clusters, Avg cluster size, Total volume
Add "Next Step" button: "Generate Ideas →" to /planner/ideas

Ideas Page

Location: frontend/src/pages/Planner/Ideas.tsx

Feature	Status	Current	Required	Action
PageHeader	✅	Has title, badge, tabs	✅ Good	None
StepBanner	❌	None	Show "Step 3/3: Generate Ideas"	Add component
Helper	❌	None	"Content ideas generated from clusters"	Add welcome message
Progress Modal	✅	useProgressModal for ideas	Fix generic "preparing clusters"	Update backend messages
Metrics Panel	❌	None	Ideas, Cluster hubs, Word count estimates	Add component
Content Structure Badge	✅	Shows badge	Add tooltip to badge	Add tooltip
Next Step Button	❌	None	"Create Tasks →"	Add button

Required Changes:

Add StepBanner showing step 3/3 in Planner workflow
Add HelperNotification: "Content ideas are generated from your clusters"
Add Tooltip on content structure badge explaining structure type
Add MetricsPanel: Total ideas, Cluster hubs, Est. word count
Add "Next Step" button: "Create Tasks →" to convert ideas to tasks
Backend: Update idea generation to include cluster names in details

WRITER MODULE

Tasks Page

Location: frontend/src/pages/Writer/Tasks.tsx

Feature	Status	Current	Required	Action
PageHeader	✅	Has title, badge, tabs	✅ Good	None
StepBanner	❌	None	Show "Step 1/3: Queue Tasks"	Add component
Helper	❌	None	"Tasks are content generation jobs"	Add welcome message
Progress Modal	✅	useProgressModal for content	Fix generic "writing article"	Update backend with title & word count
Metrics Panel	❌	None	Total, Queued, Completed, Total words	Add component
Status Badges	✅	Shows status	Add tooltips to badges	Add tooltips
Next Step Button	❌	None	"Generate Content →"	Add button

Required Changes:

Add StepBanner showing step 1/3 in Writer workflow
Add HelperNotification: "Tasks are content generation jobs queued for AI"
Add Tooltip on status badges explaining each status
Add MetricsPanel: Total tasks, Queued, Completed, Total words
Add "Next Step" button: "Generate Content →" trigger bulk generation
Backend: Include task title and target word count in progress details

Content Page

Location: frontend/src/pages/Writer/Content.tsx

Feature	Status	Current	Required	Action
PageHeader	✅	Has title, badge, tabs	✅ Good	None
StepBanner	❌	None	Show "Step 2/3: Review Content"	Add component
Helper	❌	None	"Review and edit AI-generated content"	Add welcome message
Progress Modal	✅	For image prompts	Fix prompt count extraction	Update backend to return counts
Metrics Panel	❌	None	Total, Drafts, Published, Total words	Add component
Status Badges	✅	Shows status	Add tooltips	Add tooltips
Next Step Button	❌	None	"Generate Images →"	Add button

Required Changes:

Add StepBanner showing step 2/3 in Writer workflow
Add HelperNotification: "Review and edit AI-generated content before publishing"
Add Tooltip on status badges (draft/review/published)
Add MetricsPanel: Total content, Drafts, Published, Total words
Add "Next Step" button: "Generate Images →" to /writer/images
Backend: Return structured prompt counts in result

Images Page

Location: frontend/src/pages/Writer/Images.tsx

Feature	Status	Current	Required	Action
PageHeader	✅	Has title, badge, tabs	✅ Good	None
StepBanner	❌	None	Show "Step 3/3: Generate Images"	Add component
Helper	❌	None	"Generate images from AI prompts"	Add welcome message
Progress Modal	✅	ImageQueueModal	Harmonize with ProgressModal	Consider refactor
Metrics Panel	❌	None	Total images, Generated, Published	Add component
Image Preview	✅	Hover preview	Add tooltip	None needed
Next Step Button	❌	None	"Publish to WordPress →"	Add button

Required Changes:

Add StepBanner showing step 3/3 in Writer workflow
Add HelperNotification: "Generate images for your content from AI prompts"
Add MetricsPanel: Total images, Generated, Published
Add "Next Step" button: "Publish to WordPress →" to publish flow
Consider harmonizing ImageQueueModal with ProgressModal pattern

AUTOMATION MODULE

Automation Page

Location: frontend/src/pages/Automation/AutomationPage.tsx

Feature	Status	Current	Required	Action
PageHeader	✅	Has title, badge	No tabs (not needed)	None
StepBanner	❌	Shows stage cards instead	Keep current approach	None
Helper	❌	None	"Automation runs workflow automatically"	Add helper
Stage Progress	🔴	Broken	Fix queue items, counts	Critical fix needed
Progress Bar	🔴	Inaccurate	Fix calculation	Fix
Real-time Updates	🟡	Partial	Optimize polling	Improve
Metrics Display	✅	Stage cards show metrics	Fix accuracy	Update logic

Critical Issues:

Issue	Impact	Location	Fix Required
Wrong queue items displayed	Users see incorrect tasks in queue	Stage cards	Fix stage result parsing
Missing queue items	Some items don't appear	Stage cards	Fix API response structure
Progress bar doesn't progress	Users can't see actual progress	Progress bar component	Fix percentage calculation
Total/processed counts buggy	Metrics don't add up	Stage cards	Fix backend stage_X_result JSON

Required Changes:

Add HelperNotification: "Automation runs the entire workflow automatically"
Fix stage progress cards to show accurate queue items:
- Parse stage_X_result JSON correctly
- Show pending, processing, completed, failed lists
Fix progress bar calculation:
- Formula: (completed_stages * 100 / 7) + (current_stage_progress / 7)
Fix stage metrics to show accurate counts:
- Keywords processed → clusters created
- Clusters processed → ideas created
- Ideas → tasks → content → images
Add real-time stage updates without excessive polling
Display estimated completion time
Show credit consumption per stage

End of Audit Document

File: backend/igny8_core/common/status_enums.py (NEW)

GENERATION_STATUS_CHOICES = [
    ('pending', 'Pending'),
    ('queued', 'Queued'),
    ('processing', 'Processing'),
    ('completed', 'Completed'),
    ('failed', 'Failed'),
    ('cancelled', 'Cancelled'),
]

CONTENT_STATUS_CHOICES = [
    ('draft', 'Draft'),
    ('review', 'Review'),
    ('published', 'Published'),
    ('archived', 'Archived'),
]

1.2 Add generation_status Fields

Migrations Required:

Model	Field	Default	Migration File
Keywords	`generation_status`	`'pending'`	`0014_add_keywords_generation_status.py`
Clusters	`generation_status`	`'pending'`	`0015_add_clusters_generation_status.py`
Content	`generation_status`	`'pending'`	`0016_add_content_generation_status.py`

Update Status Choices:

Model	Action	Migration File
ContentIdeas	Add `processing`, `failed`, `cancelled`	`0017_update_ideas_status_choices.py`
Tasks	Add `processing`, `failed`, `cancelled`	`0018_update_tasks_status_choices.py`

1.3 Enhance ProgressTracker

File: backend/igny8_core/ai/tracker.py

Changes:

class ProgressTracker:
    def update(
        self,
        phase: str,
        percentage: int,
        message: str,
        details: Dict = None  # NEW
    ):
        """
        details = {
            'items_total': int,
            'items_processed': int,
            'current_item': str,
            'current_item_name': str,
            'estimated_seconds_remaining': int,
        }
        """
        if self.task:
            self.task.update_state(
                state='PROGRESS',
                meta={
                    'phase': phase,
                    'percentage': percentage,
                    'message': message,
                    'details': details or {},  # Include details
                    'current': self.current,
                    'total': self.total,
                }
            )

1.4 Update AI Function Progress Messages

Files to Update:

auto_cluster.py:

# PREP phase
tracker.update(
    phase='PREP',
    percentage=10,
    message=f"Loading {len(keywords)} keywords for clustering",
    details={
        'items_total': len(keywords),
        'items_processed': 0,
    }
)

# AI_CALL phase (in loop)
tracker.update(
    phase='AI_CALL',
    percentage=20 + (processed * 60 / total),
    message=f"Analyzing keyword relationships ({processed}/{total})",
    details={
        'items_total': total,
        'items_processed': processed,
        'current_item': 'keyword',
        'current_item_name': current_keyword.keyword,
    }
)

# SAVE phase
tracker.update(
    phase='SAVE',
    percentage=90,
    message=f"Creating {len(clusters)} clusters",
    details={
        'items_total': len(clusters),
    }
)

generate_ideas.py:

# PREP phase
tracker.update(
    phase='PREP',
    percentage=10,
    message=f"Preparing {len(clusters)} cluster(s) for idea generation",
    details={'items_total': len(clusters)}
)

# AI_CALL phase (per cluster)
tracker.update(
    phase='AI_CALL',
    percentage=20 + (idx * 60 / total),
    message=f"Generating ideas for cluster: {cluster.name}",
    details={
        'items_total': total,
        'items_processed': idx,
        'current_item_name': cluster.name,
    }
)

generate_content.py:

# PREP phase
tracker.update(
    phase='PREP',
    percentage=10,
    message=f"Preparing task: {task.title}",
    details={'current_item_name': task.title}
)

# AI_CALL phase
tracker.update(
    phase='AI_CALL',
    percentage=50,
    message=f"Writing {task.word_count}-word article: {task.title}",
    details={
        'current_item_name': task.title,
        'word_count': task.word_count,
    }
)

generate_image_prompts.py:

# PARSE phase
tracker.update(
    phase='PARSE',
    percentage=70,
    message=f"Writing {len(in_article_prompts)} in-article image prompts",
    details={'prompt_count': len(in_article_prompts)}
)

generate_images.py:

# AI_CALL phase (in loop)
tracker.update(
    phase='AI_CALL',
    percentage=20 + (idx * 70 / total),
    message=f"Generating image {idx + 1}/{total}: {prompt[:50]}...",
    details={
        'items_total': total,
        'items_processed': idx,
        'current_item_name': prompt[:100],
    }
)

1.5 Return Structured Completion Data

Update Celery task return values:

# In each AI function, return structured summary
return {
    'status': 'completed',
    'summary': {
        'message': 'Clustering complete',
        'details': f"{keywords_processed} keywords mapped into {clusters_created} clusters",
        'counts': {
            'keywords_processed': keywords_processed,
            'clusters_created': clusters_created,
        }
    },
    'results': [...],
}

Phase 2: Frontend Progress Refactor (Week 1-2)

2.1 Simplify useProgressModal Hook

File: frontend/src/hooks/useProgressModal.ts

Changes:

Remove regex extraction logic (Lines 90-120, ~100 lines)

Simplify getStepInfo():

const getStepInfo = (state: any): ProgressDisplay => {
  const details = state.meta?.details || {};

  return {
    percentage: state.meta?.percentage || 0,
    message: state.meta?.message || 'Processing...',
    itemProgress: details.items_total 
      ? `${details.items_processed || 0}/${details.items_total}`
      : null,
    currentItem: details.current_item_name || null,
  };
};

Update polling to use backend details directly

2.2 Simplify ProgressModal Component

File: frontend/src/components/common/ProgressModal.tsx

Changes:

Replace getSuccessMessage() with simple backend lookup:

const getSuccessMessage = (taskResult: any): string => {
  return taskResult?.summary?.details || 'Task completed successfully';
};

Remove all regex extraction (Lines 30-130)
Use backend step definitions instead of hardcoded function checks

2.3 Add Real-Time Status Updates to Tables

Files: All page components with tables

Changes:

Add status column to tables showing badge
Update row status in real-time during processing
Show animated spinner for "processing" status
Auto-reload row data on completion

Example:

// In Keywords table
<td>
  {keyword.generation_status === 'processing' && (
    <Badge color="blue" icon={<SpinnerIcon className="animate-spin" />}>
      Processing
    </Badge>
  )}
  {keyword.generation_status === 'completed' && (
    <Badge color="green">Completed</Badge>
  )}
</td>

Phase 3: Create New UX Components (Week 2)

3.1 StepBanner Component

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

Implementation:

import React from 'react';
import { Link } from 'react-router-dom';

interface Step {
  label: string;
  href: string;
  completed: boolean;
}

interface StepBannerProps {
  currentStep: number;
  totalSteps: number;
  steps: Step[];
}

export default function StepBanner({ currentStep, totalSteps, steps }: StepBannerProps) {
  return (
    <div className="bg-gradient-to-r from-brand-50 to-brand-100 dark:from-brand-900/20 dark:to-brand-800/20 border border-brand-200 dark:border-brand-700 rounded-lg p-4 mb-6">
      <p className="text-sm font-semibold text-brand-700 dark:text-brand-300 mb-2">
        Step {currentStep} of {totalSteps}: {steps[currentStep - 1]?.label}
      </p>
      <div className="flex items-center gap-2">
        {steps.map((step, idx) => (
          <React.Fragment key={idx}>
            {step.completed ? (
              <Link 
                to={step.href}
                className="flex items-center gap-1 text-sm text-green-600 dark:text-green-400 hover:underline"
              >
                <span>✓</span> {idx + 1}. {step.label}
              </Link>
            ) : idx === currentStep - 1 ? (
              <span className="flex items-center gap-1 text-sm font-medium text-brand-600 dark:text-brand-400">
                <span>●</span> {idx + 1}. {step.label}
              </span>
            ) : (
              <span className="flex items-center gap-1 text-sm text-gray-400 dark:text-gray-600">
                {idx + 1}. {step.label}
              </span>
            )}
            {idx < steps.length - 1 && (
              <span className="text-gray-400">→</span>
            )}
          </React.Fragment>
        ))}
      </div>
    </div>
  );
}

3.2 HelperNotification Component

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

Implementation:

import React, { useState, useEffect } from 'react';
import Button from '../ui/button/Button';

interface HelperAction {
  label: string;
  href?: string;
  onClick?: () => void;
}

interface HelperNotificationProps {
  type: 'welcome' | 'info' | 'tip' | 'warning' | 'success';
  title: string;
  message: string;
  actions?: HelperAction[];
  dismissible?: boolean;
  pageKey: string; // Used for localStorage persistence
}

export default function HelperNotification({
  type,
  title,
  message,
  actions,
  dismissible = true,
  pageKey,
}: HelperNotificationProps) {
  const storageKey = `helper_dismissed_${pageKey}`;
  const [isDismissed, setIsDismissed] = useState(false);

  useEffect(() => {
    const dismissed = localStorage.getItem(storageKey);
    if (dismissed === 'true') {
      setIsDismissed(true);
    }
  }, [storageKey]);

  const handleDismiss = () => {
    localStorage.setItem(storageKey, 'true');
    setIsDismissed(true);
  };

  if (isDismissed) return null;

  const colors = {
    welcome: 'bg-blue-50 border-blue-200 text-blue-900 dark:bg-blue-900/20 dark:border-blue-700 dark:text-blue-100',
    info: 'bg-gray-50 border-gray-200 text-gray-900 dark:bg-gray-800/50 dark:border-gray-700 dark:text-gray-100',
    tip: 'bg-green-50 border-green-200 text-green-900 dark:bg-green-900/20 dark:border-green-700 dark:text-green-100',
    warning: 'bg-orange-50 border-orange-200 text-orange-900 dark:bg-orange-900/20 dark:border-orange-700 dark:text-orange-100',
    success: 'bg-emerald-50 border-emerald-200 text-emerald-900 dark:bg-emerald-900/20 dark:border-emerald-700 dark:text-emerald-100',
  };

  const icons = {
    welcome: '💡',
    info: 'ℹ️',
    tip: '✨',
    warning: '⚠️',
    success: '✅',
  };

  return (
    <div className={`rounded-lg border p-4 mb-6 ${colors[type]}`}>
      <div className="flex items-start gap-3">
        <span className="text-2xl">{icons[type]}</span>
        <div className="flex-1">
          <h4 className="font-semibold mb-1">{title}</h4>
          <p className="text-sm mb-3">{message}</p>
          {actions && actions.length > 0 && (
            <div className="flex gap-2">
              {actions.map((action, idx) => (
                <Button
                  key={idx}
                  variant="secondary"
                  size="sm"
                  onClick={action.onClick}
                >
                  {action.label}
                </Button>
              ))}
            </div>
          )}
        </div>
        {dismissible && (
          <button
            onClick={handleDismiss}
            className="text-gray-400 hover:text-gray-600 dark:text-gray-500 dark:hover:text-gray-300"
          >
            ×
          </button>
        )}
      </div>
    </div>
  );
}

3.3 Other Components

Create these components following similar patterns:

InlineGuidance.tsx - Simple text with icon
Breadcrumbs.tsx - Navigation trail with links
MetricsPanel.tsx - Collapsible metrics display
NotificationDropdown.tsx - Bell icon with dropdown list

Phase 4: Update All Pages (Week 3)

4.1 Planner Pages

Apply to: Keywords.tsx, Clusters.tsx, Ideas.tsx

Changes per page:

Import new components
Add StepBanner at top
Add HelperNotification below StepBanner
Add Tooltips to icons and buttons
Add MetricsPanel at bottom
Add "Next Step" button to actions bar

4.2 Writer Pages

Apply to: Tasks.tsx, Content.tsx, Images.tsx

Changes per page:

Import new components
Add StepBanner at top
Add HelperNotification below StepBanner
Add Tooltips to status badges
Add MetricsPanel at bottom
Add "Next Step" button to actions bar

4.3 Automation Page

File: frontend/src/pages/Automation/AutomationPage.tsx

Critical Fixes:

Fix stage progress card data parsing
Fix queue item display (pending/processing/completed/failed)
Fix progress bar calculation
Add real-time stage updates
Add HelperNotification

Phase 5: Testing & QA (Week 3)

5.1 Manual AI Function Tests

Test	Page	Action	Expected Result
Clustering	Keywords	Select 50 keywords, run clustering	Modal shows accurate counts, creates clusters
Ideas	Ideas	Select 3 clusters, generate ideas	Modal shows cluster names, creates ideas
Content	Tasks	Select 1 task, generate	Modal shows task title & word count
Image Prompts	Content	Generate prompts	Modal shows "1 Featured + X In-article prompts"
Images	Images	Generate images	Shows each image with accurate progress

5.2 Automation Wizard Tests

Test	Expected Result
Stage 1: Clustering	Shows accurate keyword → cluster counts
Stage 2: Ideas	Shows cluster → idea counts
Stage 3: Tasks	Shows idea → task conversion
Stage 4: Content	Shows task → content generation
Pause/Resume	Continues from pause point
Cancel	Stops and shows cancelled state
Queue Display	Shows correct pending/processing/completed items per stage

5.3 UX Component Tests

Component	Test	Expected
StepBanner	Click completed step	Navigates to that page
HelperNotification	Dismiss	Persists dismissal in localStorage
Tooltip	Hover	Shows after 300ms delay
MetricsPanel	Collapse	Collapses and shows summary
Breadcrumbs	Click	Navigates to parent pages

Summary of Required Changes

Backend Changes

Priority	Change	Files	Effort
P0	Create unified status enums	`common/status_enums.py` (NEW)	2h
P0	Add migrations for generation_status	4 migration files	4h
P0	Enhance ProgressTracker with details	`ai/tracker.py`	3h
P0	Update AI function messages	5 AI function files	8h
P1	Return structured completion data	All AI functions	4h

Total Backend Effort: ~21 hours

Frontend Changes

Priority	Change	Files	Effort
P0	Simplify useProgressModal	`hooks/useProgressModal.ts`	4h
P0	Simplify ProgressModal	`components/common/ProgressModal.tsx`	3h
P0	Create StepBanner	`components/workflow/StepBanner.tsx` (NEW)	4h
P0	Create HelperNotification	`components/helper/HelperNotification.tsx` (NEW)	4h
P1	Create MetricsPanel	`components/dashboard/MetricsPanel.tsx` (NEW)	6h
P1	Create Breadcrumbs	`components/navigation/Breadcrumbs.tsx` (NEW)	3h
P2	Create InlineGuidance	`components/helper/InlineGuidance.tsx` (NEW)	2h
P2	Enhance Tooltip	`components/ui/tooltip/Tooltip.tsx`	3h
P0	Fix Automation stage progress	`pages/Automation/AutomationPage.tsx`	8h
P0	Update Keywords page	`pages/Planner/Keywords.tsx`	4h
P0	Update Clusters page	`pages/Planner/Clusters.tsx`	3h
P0	Update Ideas page	`pages/Planner/Ideas.tsx`	3h
P0	Update Tasks page	`pages/Writer/Tasks.tsx`	4h
P0	Update Content page	`pages/Writer/Content.tsx`	3h
P0	Update Images page	`pages/Writer/Images.tsx`	3h

Total Frontend Effort: ~57 hours

Total Project Effort

Phase	Effort	Duration
Backend Foundation	21h	Week 1
Frontend Refactor	20h	Week 1-2
New Components	22h	Week 2
Page Updates	20h	Week 3
Testing & QA	15h	Week 3
TOTAL	98h	3 weeks

Success Criteria

Backend

✅ All models have proper status fields with full choices
✅ All AI functions emit detailed progress with item counts
✅ All AI functions return structured completion data
✅ Progress messages are specific and accurate

Frontend

✅ Progress modal shows accurate counts without regex parsing
✅ All 5 new UX components created and working
✅ All Planner/Writer pages have StepBanner, Helper, Metrics
✅ Automation stage progress is accurate
✅ All tooltips working with keyboard accessibility

UX

✅ Users understand current workflow step (StepBanner)
✅ Users get contextual help (HelperNotification)
✅ Users see real-time metrics (MetricsPanel)
✅ Progress messages are clear and accurate
✅ Automation progress is transparent and accurate

Implementation Notes

Backwards Compatibility: New generation_status fields should not break existing queries
Migration Strategy: Run migrations in dev → staging → production with testing at each stage
localStorage Cleanup: Consider adding "Reset all helpers" option in settings
Performance: MetricsPanel should not cause extra API calls (use existing data)
Accessibility: All new components must support keyboard navigation
Dark Mode: All new components must have proper dark mode styles

End of Audit Document

36 KiB Raw Blame History Unescape Escape

Implementation Audit & Action Plan

Table of Contents

UX Components Audit

Components Required by ITEM-4 but Missing

Existing Components (Good)

New Components to Create

1. StepBanner Component

2. HelperNotification Component

3. InlineGuidance Component

4. Breadcrumbs Component

5. MetricsPanel Component

6. NotificationDropdown Component

Tooltip Component Enhancement

Page Structure Audit

Current Page Structure (Planner/Writer Pages)

Required Page Structure (Standardized)

Page Header Usage Analysis

Module-by-Module Implementation Status

PLANNER MODULE

Keywords Page

Clusters Page

Ideas Page

WRITER MODULE

Tasks Page

Content Page

Images Page

AUTOMATION MODULE

Automation Page

1.2 Add generation_status Fields

1.3 Enhance ProgressTracker

1.4 Update AI Function Progress Messages

1.5 Return Structured Completion Data

Phase 2: Frontend Progress Refactor (Week 1-2)

2.1 Simplify useProgressModal Hook

2.2 Simplify ProgressModal Component

2.3 Add Real-Time Status Updates to Tables

Phase 3: Create New UX Components (Week 2)

3.1 StepBanner Component

3.2 HelperNotification Component

3.3 Other Components

Phase 4: Update All Pages (Week 3)

4.1 Planner Pages

4.2 Writer Pages

4.3 Automation Page

Phase 5: Testing & QA (Week 3)

5.1 Manual AI Function Tests

5.2 Automation Wizard Tests

5.3 UX Component Tests

Summary of Required Changes

Backend Changes

Frontend Changes

Total Project Effort

Success Criteria

Backend

Frontend

UX

Implementation Notes

36 KiB

Raw Blame History