igny8/COMPREHENSIVE-AUDIT-REPORT.md

# IGNY8 Comprehensive UX Audit & Recommendations

**Date:** December 27, 2025  
**Scope:** Complete application audit for optimal user experience

---

## Table of Contents

1. [Site & Sector Selector Placement](#1-site--sector-selector-placement)
2. [Metrics System Recommendations](#2-metrics-system-recommendations)
3. [Progress Modal Steps Audit](#3-progress-modal-steps-audit)
4. [Dashboard Redesign Plan](#4-dashboard-redesign-plan)
5. [Site Setup Checklist Implementation](#5-site-setup-checklist-implementation)
6. [To-Do-s Completion Audit](#6-to-do-s-completion-audit)
7. [Notification System Plan](#7-notification-system-plan)

---

## 1. Site & Sector Selector Placement

### Rationale
- **Site Selector**: Required when data is scoped to a specific site
- **Sector Selector**: Required when data can be further filtered by content category/niche
- **Both**: When user needs precise data filtering at granular level
- **None**: When page is not site-specific or shows account-level data

### Recommendations by Page

| Page | Site Selector | Sector Selector | Reason |
|------|:-------------:|:---------------:|--------|
| **DASHBOARD** |
| Home | ✅ All Sites option | ❌ | Overview across sites - sector too granular for dashboard |
| **SETUP** |
| Add Keywords | ✅ | ✅ | Keywords are site+sector specific |
| Content Settings | ✅ | ❌ | Settings are site-level, not sector-level |
| Sites List | ❌ | ❌ | Managing sites themselves |
| Site Dashboard | ❌ (context) | ❌ | Already in specific site context |
| Site Settings tabs | ❌ (context) | ❌ | Already in specific site context |
| **PLANNER** |
| Keywords | ✅ | ✅ | Keywords organized by site+sector |
| Clusters | ✅ | ✅ | Clusters organized by site+sector |
| Cluster Detail | ❌ (context) | ❌ (context) | Already in cluster context |
| Ideas | ✅ | ✅ | Ideas organized by site+sector |
| **WRITER** |
| Tasks/Queue | ✅ | ✅ | Tasks organized by site+sector |
| Content/Drafts | ✅ | ✅ | Content organized by site+sector |
| Content View | ❌ (context) | ❌ (context) | Viewing specific content |
| Images | ✅ | ✅ | Images tied to content by site+sector |
| Review | ✅ | ✅ | Review queue by site+sector |
| Published | ✅ | ✅ | Published content by site+sector |
| **AUTOMATION** |
| Automation | ✅ | ❌ | Automation runs at site level |
| **LINKER** (if enabled) |
| Content List | ✅ | ✅ | Linking is content-specific |
| **OPTIMIZER** (if enabled) |
| Content Selector | ✅ | ✅ | Optimization is content-specific |
| Analysis Preview | ❌ (context) | ❌ (context) | Already in analysis context |
| **THINKER** (Admin) |
| All Thinker pages | ❌ | ❌ | System-wide prompts/profiles |
| **BILLING** |
| All Billing pages | ❌ | ❌ | Account-level billing data |
| **ACCOUNT** |
| Account Settings | ❌ | ❌ | Account-level settings |
| Profile | ❌ | ❌ | User profile |
| Team | ❌ | ❌ | Account-wide team |
| Plans | ❌ | ❌ | Account-level plans |
| Usage | ❌ | ❌ | Account-level usage |
| **HELP** |
| Help Page | ❌ | ❌ | Documentation |

### Implementation Priority
1. **High**: Ensure Planner & Writer pages show both selectors
2. **Medium**: Automation shows site only
3. **Low**: Account/Billing/Thinker show none

---

## 2. Metrics System Recommendations

### A. Header Metrics Bar (Table Action Row)

**Current**: Shows Credits + optional page metrics  
**Problem**: Limited space, unclear what metrics mean, no actionable insights

#### Recommended Header Metrics by Page

##### Keywords Page
| Metric | Value Example | Tooltip |
|--------|---------------|---------|
| Keywords | `46` | Total keywords in current view. Add more to expand your content pipeline. |
| Clustered | `10` | Keywords organized into clusters. Unclustered keywords need grouping before idea generation. |
| Unmapped | `0` | Keywords not assigned to clusters. Select unmapped keywords and click "Auto Cluster" to organize them. |
| Volume | `13.6K` | Combined monthly search volume of your keywords. Higher volume = more potential traffic. |

##### Clusters Page
| Metric | Value Example | Tooltip |
|--------|---------------|---------|
| Clusters | `12` | Total keyword clusters. Each cluster can generate multiple content ideas. |
| With Ideas | `8` | Clusters that have generated content ideas. Click a cluster without ideas to "Generate Ideas". |
| Avg Size | `4.2` | Average keywords per cluster. 3-7 keywords per cluster is optimal for focused content. |
| Ready | `4` | Clusters ready for idea generation (have keywords, no ideas yet). |

##### Ideas Page
| Metric | Value Example | Tooltip |
|--------|---------------|---------|
| Ideas | `34` | Content ideas ready to become articles. Select ideas and click "Create Tasks". |
| Pending | `12` | Ideas not yet converted to tasks. Convert ideas to tasks to begin content creation. |
| In Tasks | `22` | Ideas already converted to writing tasks. View in Writer → Tasks. |

##### Tasks Page
| Metric | Value Example | Tooltip |
|--------|---------------|---------|
| Queue | `15` | Tasks waiting for content generation. Select tasks and click "Generate Content". |
| Processing | `2` | Tasks currently being written by AI. Content will appear in Drafts when complete. |
| Complete | `28` | Tasks with generated content. View and edit in Writer → Content. |

##### Content/Drafts Page
| Metric | Value Example | Tooltip |
|--------|---------------|---------|
| Drafts | `25` | Content pieces in draft status. Review and approve to move to publishing. |
| Pending Images | `8` | Drafts missing images. Select and click "Generate Images" to create visuals. |
| Ready to Review | `17` | Drafts with complete content and images. Click "Send to Review" when ready. |

##### Review Page
| Metric | Value Example | Tooltip |
|--------|---------------|---------|
| In Review | `5` | Content awaiting your review. Approve to move to publishing queue. |
| This Week | `12` | Content reviewed this week. Stay on top of reviews to maintain workflow. |

##### Published Page
| Metric | Value Example | Tooltip |
|--------|---------------|---------|
| Published | `45` | Content successfully published to WordPress. |
| This Month | `12` | Content published this billing cycle. |
| Total Words | `52.3K` | Total words published. Great for tracking content velocity! |

### B. Module Metrics Footer (Below Tables)

**Current Problem**: Cards too large, not enough actionable info, unclear relationship to user's workflow

#### Recommended Footer Design: Compact Information Cards

**New Size**: Reduce card padding from `p-5 md:p-6` to `p-3 md:p-4`  
**Layout**: 4-column grid on desktop, 2-column on tablet, 1-column on mobile

#### Keywords Page Footer

| Card | Title | Value | Subtitle | Color | Action |
|------|-------|-------|----------|-------|--------|
| 1 | Total Keywords | `46` | `10 clusters` | blue | → Keywords |
| 2 | Clustered | `42` | `91% organized` | green | → Clusters |
| 3 | Easy Wins | `8` | `Low difficulty, high volume` | orange | Filter low diff |
| 4 | Unmapped | `4` | `Need clustering` | purple | Select unmapped |

**Progress Bar**: `Keyword Pipeline: 91% clustered`

#### Clusters Page Footer

| Card | Title | Value | Subtitle | Color | Action |
|------|-------|-------|----------|-------|--------|
| 1 | Clusters | `12` | `46 keywords` | blue | - |
| 2 | With Ideas | `8` | `67% have ideas` | green | → Ideas |
| 3 | Ready | `4` | `Can generate ideas` | orange | Select ready |
| 4 | Empty | `0` | `No keywords` | purple | - |

**Progress Bar**: `Idea Pipeline: 67% clusters have ideas`

#### Tasks Page Footer

| Card | Title | Value | Subtitle | Color | Action |
|------|-------|-------|----------|-------|--------|
| 1 | Ideas | `34` | `From 12 clusters` | blue | → Planner/Ideas |
| 2 | In Queue | `15` | `Awaiting AI` | orange | - |
| 3 | Processing | `2` | `Writing now` | purple | - |
| 4 | Complete | `28` | `Ready for review` | green | → Content |

**Progress Bar**: `Content Pipeline: 62% tasks complete`

#### Content Page Footer

| Card | Title | Value | Subtitle | Color | Action |
|------|-------|-------|----------|-------|--------|
| 1 | Drafts | `25` | `12.5K words` | blue | - |
| 2 | Has Images | `17` | `68% visual` | green | - |
| 3 | Needs Images | `8` | `Generate images` | orange | Select no images |
| 4 | Ready | `17` | `Complete & ready` | success | Send to review |

**Progress Bar**: `Image Pipeline: 68% have images`

### C. Additional Explainer Text

Add a subtle helper line below metrics footer (optional, can be toggled off):

```
💡 Next step: 8 drafts need images. Select them and click "Generate Images" to complete.
```

This contextual guidance appears based on current data state.

---

## 3. Progress Modal Steps Audit

### Current Issues
- Generic messages lacking context
- Missing counts where data is available
- Inconsistent terminology
- Not professional/polished

### Recommended Progress Step Text

#### Auto Cluster Keywords

| Phase | Current | Recommended |
|-------|---------|-------------|
| INIT | Validating keywords | Validating {count} keywords for clustering |
| PREP | Loading keyword data | Analyzing keyword relationships |
| AI_CALL | Generating clusters with Igny8 Semantic SEO Model | Grouping keywords by search intent ({count} keywords) |
| PARSE | Organizing clusters | Organizing {cluster_count} semantic clusters |
| SAVE | Saving clusters | Saving {cluster_count} clusters with {keyword_count} keywords |
| DONE | Clustering complete! | ✓ Created {cluster_count} clusters from {keyword_count} keywords |

#### Generate Ideas

| Phase | Current | Recommended |
|-------|---------|-------------|
| INIT | Verifying cluster integrity | Analyzing {count} clusters for content opportunities |
| PREP | Loading cluster keywords | Mapping {keyword_count} keywords to topic briefs |
| AI_CALL | Generating ideas with Igny8 Semantic AI | Generating content ideas for {cluster_count} clusters |
| PARSE | High-opportunity ideas generated | Structuring {idea_count} article outlines |
| SAVE | Content Outline for Ideas generated | Saving {idea_count} content ideas with outlines |
| DONE | Ideas generated! | ✓ Generated {idea_count} content ideas from {cluster_count} clusters |

#### Generate Content

| Phase | Current | Recommended |
|-------|---------|-------------|
| INIT | Validating task | Preparing {count} article{s} for generation |
| PREP | Preparing content idea | Building content brief with {keyword_count} target keywords |
| AI_CALL | Writing article with Igny8 Semantic AI | Writing {count} article{s} (~{word_target} words each) |
| PARSE | Formatting content | Formatting HTML content and metadata |
| SAVE | Saving article | Saving {count} article{s} ({total_words} words) |
| DONE | Content generated! | ✓ {count} article{s} generated ({total_words} words total) |

#### Generate Image Prompts

| Phase | Current | Recommended |
|-------|---------|-------------|
| INIT | Checking content and image slots | Analyzing content for {count} image opportunities |
| PREP | Mapping content for image prompts | Identifying featured image and {in_article_count} in-article image slots |
| AI_CALL | Writing Featured Image Prompts | Creating optimized prompts for {count} images |
| PARSE | Writing In‑article Image Prompts | Refining {in_article_count} contextual image descriptions |
| SAVE | Assigning Prompts to Dedicated Slots | Assigning {count} prompts to image slots |
| DONE | Prompts generated! | ✓ {count} image prompts ready (1 featured + {in_article_count} in-article) |

#### Generate Images from Prompts

| Phase | Current | Recommended |
|-------|---------|-------------|
| INIT | Validating image prompts | Queuing {count} images for generation |
| PREP | Preparing image generation queue | Preparing AI image generation ({count} images) |
| AI_CALL | Generating images with AI | Generating image {current}/{count}... |
| PARSE | Processing image URLs | Processing {count} generated images |
| SAVE | Saving image URLs | Uploading {count} images to media library |
| DONE | Images generated! | ✓ {count} images generated and saved |

### Success Message Templates (with counts)

```typescript
// Clustering
`✓ Organized ${keywordCount} keywords into ${clusterCount} semantic clusters`

// Ideas
`✓ Created ${ideaCount} content ideas with detailed outlines`

// Content
`✓ Generated ${articleCount} articles (${totalWords.toLocaleString()} words)`

// Image Prompts
`✓ Created prompts for ${imageCount} images (1 featured + ${inArticleCount} in-article)`

// Image Generation
`✓ Generated and saved ${imageCount} AI images`
```

---

## 4. Dashboard Redesign Plan

### Current Issues
- Too much whitespace
- Large headings with little content
- Workflow guide takes too much space
- Not actionable at a glance
- Missing "needs attention" items
- Missing recent activity

### New Dashboard Layout (Compact, Information-Dense)

```
┌─────────────────────────────────────────────────────────────────────────────┐
│ ⚠ NEEDS ATTENTION (collapsible, only if items exist)                        │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ ┌─────────────────┐ │
│ │ 3 content pending review│ │ WP sync failed (Site A) │ │ Credits at 82%  │ │
│ │ [Review →]              │ │ [Retry] [Settings →]    │ │ [Upgrade →]     │ │
│ └─────────────────────────┘ └─────────────────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────┤
│ QUICK STATS (compact 4-6 column row)                                        │
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐                       │
│ │Sites │ │ KWs  │ │Clust │ │Ideas │ │Draft │ │Pub'd │ [Site: ▼ All Sites]  │
│ │  2   │ │ 156  │ │  23  │ │  67  │ │  12  │ │  45  │                       │
│ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘                       │
├─────────────────────────────────────────────────────────────────────────────┤
│ WORKFLOW PIPELINE (compact horizontal)         │ CREDITS                    │
│ Sites → Keywords → Clusters → Ideas            │ ████████░░░░░ 826/30K     │
│   ✓        156        23        67             │ ~82% remaining             │
│ → Content → Published                          │ Est. 340 articles left     │
│      12        45                              │ [View Usage →]             │
├────────────────────────────────────────────────┼────────────────────────────┤
│ QUICK ACTIONS (2 column grid)                  │ WORKFLOW GUIDE             │
│ ┌────────────────┐ ┌────────────────┐          │ 1. Add Keywords → Planner  │
│ │ + Add Keywords │ │ ⚡ Auto Cluster │          │ 2. Cluster → Auto Cluster  │
│ └────────────────┘ └────────────────┘          │ 3. Ideas → Generate Ideas  │
│ ┌────────────────┐ ┌────────────────┐          │ 4. Tasks → Create Tasks    │
│ │ 📝 Write Content│ │ 🖼 Gen Images  │          │ 5. Content → Generate      │
│ └────────────────┘ └────────────────┘          │ 6. Images → Generate       │
│ ┌────────────────┐ ┌────────────────┐          │ 7. Review → Approve        │
│ │ ✓ Review Queue │ │ 🚀 Publish     │          │ 8. Publish → WordPress     │
│ └────────────────┘ └────────────────┘          │ [Full Help →]              │
├────────────────────────────────────────────────┴────────────────────────────┤
│ RECENT ACTIVITY (compact list, max 5 items)                                 │
│ • Generated 5 articles from "Product Reviews" cluster        2 hours ago   │
│ • Created 12 image prompts for fitness content               4 hours ago   │
│ • Clustered 45 keywords into 8 groups                        Yesterday     │
│ • Published "10 Best Running Shoes" to WordPress             Yesterday     │
│ • Added 23 keywords from seed database                       2 days ago    │
│                                                              [View All →]  │
├─────────────────────────────────────────────────────────────────────────────┤
│ AUTOMATION STATUS (if enabled)                                              │
│ ● Active  Last run: 2h ago  Next: Tomorrow 9:00 AM  [Configure →] [Run →]  │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Component Specifications

#### 1. NeedsAttention Widget
```typescript
interface NeedsAttentionItem {
  type: 'pending_review' | 'sync_failed' | 'low_credits' | 'setup_incomplete' | 'automation_failed';
  title: string;
  count?: number;
  actions: Array<{ label: string; href?: string; onClick?: () => void }>;
  severity: 'warning' | 'error' | 'info';
}
```

**Triggers:**
- `pending_review`: content.review.count > 0
- `sync_failed`: site.wordpress_sync.last_error exists
- `low_credits`: usage > 80%
- `setup_incomplete`: site.setup_checklist.complete < 100%
- `automation_failed`: automation.last_run.status === 'failed'

#### 2. Quick Stats Row
- Ultra-compact metric chips
- Clickable to navigate to relevant page
- Shows current site filter or "All Sites"

#### 3. Workflow Pipeline (Compact)
- Single-line visual with numbers under each stage
- Checkmarks for completed stages
- Arrows showing flow direction
- Subtle progress indication

#### 4. Credits Widget (Compact)
- Progress bar with percentage
- Remaining estimate ("~340 articles left" based on avg cost)
- Link to usage page

#### 5. Quick Actions Grid
- 2x3 grid of action buttons
- Icons + short labels
- Direct actions (opens relevant page/modal)

#### 6. Workflow Guide (Compact)
- Numbered list (1-8 steps)
- Each step is a link
- Collapsible on mobile
- "Full Help" link to help page

#### 7. Recent Activity
- Compact list format
- Icon + description + timestamp
- Max 5 items with "View All" link
- Real data from AI task logs

#### 8. Automation Status (Conditional)
- Only shows if automation configured
- Status indicator (green dot = active)
- Last run / next run times
- Quick configure/run buttons

### Dashboard API Endpoint

Create aggregated endpoint to reduce API calls:

```typescript
// GET /api/v1/dashboard/summary/
interface DashboardSummary {
  pipeline: {
    sites: number;
    keywords: number;
    clusters: number;
    ideas: number;
    tasks_pending: number;
    content_draft: number;
    content_review: number;
    content_published: number;
  };
  credits: {
    used: number;
    limit: number;
    percentage: number;
    estimated_remaining_articles: number;
  };
  needs_attention: NeedsAttentionItem[];
  recent_activity: ActivityItem[];
  automation: {
    enabled: boolean;
    status: 'active' | 'paused' | 'failed';
    last_run: string | null;
    next_run: string | null;
  };
  sites_setup: Array<{
    site_id: number;
    site_name: string;
    checklist_complete: number; // percentage
  }>;
}
```

---

## 5. Site Setup Checklist Implementation

### Current Status
- ✅ `SiteSetupChecklist.tsx` component EXISTS
- ✅ Integrated in `Site Dashboard` page (full mode)
- ❌ **NOT integrated in `SiteCard.tsx`** (compact mode not used)

### Missing Implementation

The component has a `compact` prop but is not used in the site cards list.

### Recommended Fix

**File:** `frontend/src/components/sites/SiteCard.tsx`

Add compact checklist to each site card:

```tsx
// In SiteCard component, add after the status badges:
<SiteSetupChecklist
  siteId={site.id}
  siteName={site.name}
  hasIndustry={!!site.industry}
  hasSectors={site.sectors_count > 0}
  hasWordPressIntegration={!!site.wordpress_site_url}
  hasKeywords={site.keywords_count > 0}
  compact={true}
/>
```

**Visual Result:**
```
┌─────────────────────────────────────────┐
│ My Website                    [Active]  │
│ example.com                             │
│ Industry: Tech  │  3 Sectors            │
│ ●●●○  3/4 Setup Steps Complete          │  ← NEW compact checklist
│                              [Manage →] │
└─────────────────────────────────────────┘
```

---

## 6. To-Do-s Completion Audit

### Summary by Section

| Section | File | Status | Remaining Items |
|---------|------|--------|-----------------|
| Section 1 | `dashboard_mods.md` | 📋 Planned (do LAST) | Dashboard revamp, aggregated API |
| Section 2 | `SECTION_2_FINAL_MODS.md` | ✅ Done | - |
| Section 3 | `SECTION_3_FINAL_MODS.md` | ✅ Done | - |
| Section 4 | `SECTION_4_FINAL_MODS.md` | ✅ Done | Usage alerts, API activity data |
| Section 5 | `SECTION_5_FINAL_MODS.md` | ✅ Done | - |
| Section 6 | `SECTION_6_FINAL_MODS.md` | ✅ Done | - |
| Pricing | `pricing_simplification.md` | 📋 Planned | Credit simplification |

### Remaining Items Detail

#### Dashboard (Section 1) - Major Work
- [ ] Aggregated API endpoint `/v1/dashboard/summary/`
- [ ] NeedsAttention widget
- [ ] Real Recent Activity log (replace hardcoded)
- [ ] Automation Status display
- [ ] Real-time polling/updates
- [ ] Contextual Quick Actions

#### Usage (Section 4) - Minor Work
- [ ] Real API Activity data (currently hardcoded)
- [ ] Real success rate calculation
- [ ] Usage alerts at 80%, 90%, 100%
- [ ] Per-site usage breakdown
- [ ] Usage forecasting

#### Pricing Simplification
- [ ] Remove monthly limit fields (keep credits/keywords/sites only)
- [ ] Update CreditCostConfig values
- [ ] Add `target_word_count` to ContentSettings
- [ ] Update Usage page (credits only)

#### Cross-Module
- [ ] Notification bell dropdown with AI run logging
- [ ] Single source of truth for credit balance

---

## 7. Notification System Plan

### Current State
- Bell icon exists with placeholder/mock notifications
- No real notification system or API
- No notification persistence

### Comprehensive Notification System Design

#### A. Notification Data Model

```python
# backend/igny8_core/business/notifications/models.py

class Notification(BaseModel):
    account = models.ForeignKey('Account', on_delete=models.CASCADE)
    user = models.ForeignKey('User', on_delete=models.CASCADE, null=True)  # null = all users
    
    # Notification content
    type = models.CharField(max_length=50, choices=NOTIFICATION_TYPES)
    title = models.CharField(max_length=200)
    message = models.TextField()
    severity = models.CharField(max_length=20, choices=SEVERITY_CHOICES)
    
    # Related objects
    site = models.ForeignKey('Site', null=True, on_delete=models.CASCADE)
    content_type = models.ForeignKey(ContentType, null=True)
    object_id = models.PositiveIntegerField(null=True)
    content_object = GenericForeignKey()
    
    # Action
    action_url = models.CharField(max_length=500, null=True)
    action_label = models.CharField(max_length=50, null=True)
    
    # Status
    is_read = models.BooleanField(default=False)
    read_at = models.DateTimeField(null=True)
    
    created_at = models.DateTimeField(auto_now_add=True)

NOTIFICATION_TYPES = [
    # AI Operations
    ('ai_cluster_complete', 'Clustering Complete'),
    ('ai_cluster_failed', 'Clustering Failed'),
    ('ai_ideas_complete', 'Ideas Generated'),
    ('ai_ideas_failed', 'Idea Generation Failed'),
    ('ai_content_complete', 'Content Generated'),
    ('ai_content_failed', 'Content Generation Failed'),
    ('ai_images_complete', 'Images Generated'),
    ('ai_images_failed', 'Image Generation Failed'),
    
    # Workflow
    ('content_ready_review', 'Content Ready for Review'),
    ('content_published', 'Content Published'),
    ('content_publish_failed', 'Publishing Failed'),
    
    # WordPress Sync
    ('wordpress_sync_success', 'WordPress Sync Complete'),
    ('wordpress_sync_failed', 'WordPress Sync Failed'),
    
    # Credits/Billing
    ('credits_low', 'Credits Running Low'),
    ('credits_depleted', 'Credits Depleted'),
    ('plan_upgraded', 'Plan Upgraded'),
    
    # Setup
    ('site_setup_complete', 'Site Setup Complete'),
    ('keywords_imported', 'Keywords Imported'),
]

SEVERITY_CHOICES = [
    ('info', 'Info'),
    ('success', 'Success'),
    ('warning', 'Warning'),
    ('error', 'Error'),
]
```

#### B. Notification Creation Points

| Trigger Event | Notification Type | Severity | Title | Message Template |
|---------------|-------------------|----------|-------|------------------|
| Clustering completes | `ai_cluster_complete` | success | Clustering Complete | Created {count} clusters from {keyword_count} keywords |
| Clustering fails | `ai_cluster_failed` | error | Clustering Failed | Failed to cluster keywords: {error} |
| Ideas generated | `ai_ideas_complete` | success | Ideas Generated | Generated {count} content ideas from {cluster_count} clusters |
| Ideas failed | `ai_ideas_failed` | error | Idea Generation Failed | Failed to generate ideas: {error} |
| Content generated | `ai_content_complete` | success | Content Generated | Generated {count} articles ({word_count} words) |
| Content failed | `ai_content_failed` | error | Content Generation Failed | Failed to generate content: {error} |
| Images generated | `ai_images_complete` | success | Images Generated | Generated {count} images for your content |
| Images failed | `ai_images_failed` | error | Image Generation Failed | Failed to generate {count} images: {error} |
| Content published | `content_published` | success | Content Published | "{title}" published to {site_name} |
| Publish failed | `content_publish_failed` | error | Publishing Failed | Failed to publish "{title}": {error} |
| WP sync success | `wordpress_sync_success` | success | WordPress Synced | Synced {count} items with {site_name} |
| WP sync failed | `wordpress_sync_failed` | error | Sync Failed | WordPress sync failed for {site_name}: {error} |
| Credits at 80% | `credits_low` | warning | Credits Running Low | You've used 80% of your credits. Consider upgrading. |
| Credits at 90% | `credits_low` | warning | Credits Almost Depleted | Only 10% of credits remaining. Upgrade to continue. |
| Credits depleted | `credits_depleted` | error | Credits Depleted | Your credits are exhausted. Upgrade to continue. |
| Site setup done | `site_setup_complete` | success | Site Ready | {site_name} is fully configured and ready! |
| Keywords imported | `keywords_imported` | info | Keywords Imported | Added {count} keywords to {site_name} |

#### C. API Endpoints

```python
# GET /api/v1/notifications/
# Returns paginated list, most recent first
{
    "count": 45,
    "unread_count": 3,
    "results": [
        {
            "id": 123,
            "type": "ai_content_complete",
            "title": "Content Generated",
            "message": "Generated 5 articles (4,500 words)",
            "severity": "success",
            "site": {"id": 1, "name": "My Blog"},
            "action_url": "/writer/content",
            "action_label": "View Content",
            "is_read": false,
            "created_at": "2025-12-27T10:30:00Z"
        }
    ]
}

# POST /api/v1/notifications/{id}/read/
# Mark single notification as read

# POST /api/v1/notifications/read-all/
# Mark all notifications as read

# DELETE /api/v1/notifications/{id}/
# Delete notification
```

#### D. Frontend Integration

##### NotificationDropdown Component Updates

```tsx
// frontend/src/components/header/NotificationDropdown.tsx

interface Notification {
  id: number;
  type: string;
  title: string;
  message: string;
  severity: 'info' | 'success' | 'warning' | 'error';
  site?: { id: number; name: string };
  action_url?: string;
  action_label?: string;
  is_read: boolean;
  created_at: string;
}

// Features:
// - Fetch real notifications on mount
// - Poll every 30 seconds for new notifications
// - Show unread count badge on bell icon
// - Mark as read on click
// - Navigate to action_url on click
// - "Mark all read" button
// - "View all" link to full notifications page
```

##### Full Notifications Page

Create `/account/notifications` page with:
- Full list of all notifications (paginated)
- Filter by type, severity, site
- Bulk actions (mark read, delete)
- Date range filtering

#### E. Implementation Priority

**Phase 1 (Core):**
1. Create Notification model
2. Create API endpoints
3. Hook AI functions to create notifications on complete/fail
4. Update NotificationDropdown to fetch real data

**Phase 2 (Enhanced):**
1. Credit threshold notifications
2. WordPress sync notifications
3. Full notifications page
4. Email notifications (optional)

**Phase 3 (Polish):**
1. Notification preferences
2. Push notifications
3. Real-time updates (WebSocket)

---

## Implementation Roadmap

### Priority Order

1. **Site Setup Checklist on Cards** - Quick win, already built
2. **Notification System** - High user value
3. **Metrics Improvements** - Better user understanding
4. **Progress Modal Text** - Polish
5. **Dashboard Redesign** - Major effort, do last

### Estimated Effort

| Item | Backend | Frontend | Total |
|------|---------|----------|-------|
| Site checklist on cards | 0h | 2h | 2h |
| Notification system | 8h | 8h | 16h |
| Metrics improvements | 2h | 8h | 10h |
| Progress modal text | 4h | 4h | 8h |
| Dashboard redesign | 8h | 16h | 24h |
| **Total** | **22h** | **38h** | **60h** |

---

## Appendix: Current vs Recommended Comparison

### Header Metrics Example (Keywords Page)

**Current:**
```
| Credits 826/30K |
```

**Recommended:**
```
| Credits 826/30K | Keywords 46 ⓘ | Clustered 10 ⓘ | Unmapped 0 ⓘ | Volume 13.6K ⓘ |
```

### Footer Metrics Example (Keywords Page)

**Current:** Large cards with minimal info

**Recommended:** Compact cards with actionable data + progress bar + next step hint

### Dashboard Example

**Current:** Hero banner + large sections + much whitespace

**Recommended:** Compact info-dense layout with needs-attention, stats, pipeline, actions, activity all visible without scrolling