From 9d54bbff481bdce38b3694dab3e8e3d35d4f62ad Mon Sep 17 00:00:00 2001 From: "IGNY8 VPS (Salman)" Date: Sat, 27 Dec 2025 11:14:51 +0000 Subject: [PATCH] closing final plans --- COMPREHENSIVE-AUDIT-REPORT.md | 772 ++++++++++++++++++++++++++++++++++ 1 file changed, 772 insertions(+) create mode 100644 COMPREHENSIVE-AUDIT-REPORT.md diff --git a/COMPREHENSIVE-AUDIT-REPORT.md b/COMPREHENSIVE-AUDIT-REPORT.md new file mode 100644 index 00000000..9e09b649 --- /dev/null +++ b/COMPREHENSIVE-AUDIT-REPORT.md @@ -0,0 +1,772 @@ +# 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: + 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 +