igny8/docs/plans/automation/AUTOMATION_RUNS_DETAIL_VIEW_UX_PLAN.md

Automation Runs Detail View - UX Plan

Executive Summary

The AutomationRun model contains extremely valuable data for each stage in each run that is currently being underutilized. This plan outlines a comprehensive UX design for:

1. Enhanced Overview Page - Comprehensive dashboard with predictive analytics, cost projections, and actionable insights
2. Run Detail Page - Deep-dive into individual automation runs accessible via clickable Run Title (Site Name + Run #)

Both pages provide transparency into what was processed, what was created, how credits were consumed, and what could happen if automation runs again based on historical averages.

---

Part 1: Enhanced Automation Overview Page

Current State Issues

The current AutomationOverview.tsx shows:

• Basic metric cards (Keywords, Clusters, Ideas, Content, Images)
• Simple "Ready to Process" cost estimation
• Basic run history table (Run ID, Status, Trigger, Dates, Credits, Stage)

Missing:

• ❌ Run-level statistics (total runs, success rate, avg duration)
• ❌ Predictive cost analysis based on historical averages
• ❌ Pipeline health indicators (skipped/failed/pending items)
• ❌ Potential output projections
• ❌ Click-through to detailed run view
• ❌ Human-readable run titles (Site Name + Run #)

Proposed Enhanced Overview Design

┌─────────────────────────────────────────────────────────────────────────────────┐
│ PageHeader: Automation Overview                                                  │
│ Breadcrumb: Automation / Overview                                               │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│ ┌──────────── Automation STATISTICS SUMMARY (New Section) ────────────────────────────┐│
│ │                                                                               ││
│ │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         ││
│ │  │ Total Runs  │  │ Success Rate│  │ Avg Duration│  │ Avg Credits │         ││
│ │  │    47       │  │   94.7%     │  │  28m 15s    │  │  486 cr     │         ││
│ │  │ +5 this wk  │  │ ↑ 2.1%      │  │ ↓ 3m faster │  │ ↓ 12% less  │         ││
│ │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘         ││
│ │                                                                               ││
│ └───────────────────────────────────────────────────────────────────────────────┘│
│                                                                                  │
│ ┌──────────── PIPELINE STATUS METRICS (Enhanced) ──────────────────────────────┐│
│ │                                                                               ││
│ │  Keywords    Clusters    Ideas       Content     Images                       ││
│ │  ┌───────┐   ┌───────┐   ┌───────┐   ┌───────┐   ┌───────┐                   ││
│ │  │  150  │   │   23  │   │   87  │   │   42  │   │  156  │                   ││
│ │  │───────│   │───────│   │───────│   │───────│   │───────│                   ││
│ │  │New:120│   │New: 8 │   │New:32 │   │Draft:15│  │Pend:24│                   ││
│ │  │Map:30 │   │Map:15 │   │Queue:20│  │Review:12│ │Gen:132│                   ││
│ │  │Skip:0 │   │Skip:0 │   │Done:35│   │Pub:15 │                               ││
│ │  └───────┘   └───────┘   └───────┘   └───────┘   └───────┘                   ││
│ │                                                                               ││
│ └───────────────────────────────────────────────────────────────────────────────┘│
│                                                                                  │
│ ┌──────────── PREDICTIVE COST & OUTPUT ANALYSIS (New Section) ─────────────────┐│
│ │                                                                               ││
│ │  📊 If Automation Runs Now (Based on 10-run averages)                        ││
│ │  ─────────────────────────────────────────────────────────────────────────── ││
│ │                                                                               ││
│ │  Stage          Pending  Est Credits   Est Output      Avg Rate              ││
│ │  ─────────────  ───────  ───────────   ───────────     ─────────             ││
│ │  Keywords→Clust   120      24 cr       ~15 clusters    0.2 cr/kw             ││
│ │  Clusters→Ideas     8      16 cr       ~70 ideas       2.0 cr/cluster        ││
│ │  Ideas→Tasks       32       0 cr        32 tasks       (free)                ││
│ │  Tasks→Content     20     100 cr        20 articles    5.0 cr/task           ││
│ │  Content→Prompts   15      30 cr       ~60 prompts     2.0 cr/content        ││
│ │  Prompts→Images    24      48 cr       ~24 images      2.0 cr/prompt         ││
│ │  Review→Approved   12       0 cr        12 approved    (free)                ││
│ │  ─────────────────────────────────────────────────────────────────────────── ││
│ │                                                                               ││
│ │  TOTAL ESTIMATED:  218 credits (~20% buffer recommended = 262 credits)       ││
│ │  Current Balance:  1,250 credits  ✅ Sufficient                              ││
│ │                                                                               ││
│ │  Expected Outputs:                                                            ││
│ │  • ~15 new clusters from 120 keywords                                        ││
│ │  • ~70 content ideas from existing clusters                                  ││
│ │  • ~20 published articles (full pipeline)                                    ││
│ │  • ~24 generated images                                                      ││
│ │                                                                               ││
│ │  ⚠️ Items Requiring Attention:                                               ││
│ │  • 3 ideas marked as skipped (review in Planner)                            ││
│ │  • 2 content items failed generation (retry available)                       ││
│ │  • 5 images failed - exceeded prompt complexity                              ││
│ │                                                                               ││
│ └───────────────────────────────────────────────────────────────────────────────┘│
│                                                                                  │
│ ┌──────────── RUN HISTORY (Enhanced with Clickable Titles) ────────────────────┐│
│ │                                                                               ││
│ │  Run                          Status    Trigger  Started           Credits   ││
│ │  ─────────────────────────────────────────────────────────────────────────── ││
│ │  🔗 TechBlog.com #47          ✅ Done   Manual   Jan 17, 2:05 PM    569 cr   ││
│ │     Stages: [✓][✓][✓][✓][✓][✓][✓]  Duration: 38m 21s                        ││
│ │                                                                               ││
│ │  🔗 TechBlog.com #46          ✅ Done   Sched    Jan 16, 2:00 AM    423 cr   ││
│ │     Stages: [✓][✓][✓][✓][✓][✓][✓]  Duration: 25m 12s                        ││
│ │                                                                               ││
│ │  🔗 TechBlog.com #45          ⚠️ Partial Manual  Jan 15, 10:30 AM   287 cr   ││
│ │     Stages: [✓][✓][✓][✓][✗][ ][ ]  Duration: 18m 45s  (Stage 5 failed)      ││
│ │                                                                               ││
│ │  🔗 TechBlog.com #44          ✅ Done   Sched    Jan 14, 2:00 AM    512 cr   ││
│ │     Stages: [✓][✓][✓][✓][✓][✓][✓]  Duration: 32m 08s                        ││
│ │                                                                               ││
│ │  [Show All Runs →]                                                            ││
│ │                                                                               ││
│ └───────────────────────────────────────────────────────────────────────────────┘│
│                                                                                  │
└─────────────────────────────────────────────────────────────────────────────────┘

Backend API Enhancements for Overview

New Endpoint: /api/v1/automation/overview_stats/

GET /api/v1/automation/overview_stats/?site_id=123

Response:
{
  "run_statistics": {
    "total_runs": 47,
    "completed_runs": 44,
    "failed_runs": 3,
    "success_rate": 94.7,
    "avg_duration_seconds": 1695,
    "avg_credits_per_run": 486,
    "runs_this_week": 5,
    "credits_trend": -12.3,  // % change from previous period
    "duration_trend": -180   // seconds change from previous period
  },
  "predictive_analysis": {
    "stages": [
      {
        "stage": 1,
        "name": "Keywords → Clusters",
        "pending_items": 120,
        "avg_credits_per_item": 0.2,
        "estimated_credits": 24,
        "avg_output_ratio": 0.125,  // 1 cluster per 8 keywords
        "estimated_output": 15,
        "output_type": "clusters"
      },
      // ... stages 2-7
    ],
    "total_estimated_credits": 218,
    "recommended_buffer": 262,  // 20% buffer
    "current_balance": 1250,
    "is_sufficient": true,
    "expected_outputs": {
      "clusters": 15,
      "ideas": 70,
      "content": 20,
      "images": 24
    }
  },
  "attention_items": {
    "skipped_ideas": 3,
    "failed_content": 2,
    "failed_images": 5,
    "total_attention_needed": 10
  },
  "historical_averages": {
    "period_days": 30,
    "runs_analyzed": 10,
    "avg_credits_stage_1": 0.2,
    "avg_credits_stage_2": 2.0,
    "avg_credits_stage_4": 5.0,
    "avg_credits_stage_5": 2.0,
    "avg_credits_stage_6": 2.0,
    "avg_output_ratio_stage_1": 0.125,  // clusters per keyword
    "avg_output_ratio_stage_2": 8.7,    // ideas per cluster
    "avg_output_ratio_stage_5": 4.0,    // prompts per content
    "avg_output_ratio_stage_6": 1.0     // images per prompt
  }
}

Enhanced History Endpoint: /api/v1/automation/history/

GET /api/v1/automation/history/?site_id=123

Response:
{
  "runs": [
    {
      "run_id": "run_20260117_140523_manual",
      "run_number": 47,  // NEW: sequential run number for this site
      "run_title": "TechBlog.com #47",  // NEW: human-readable title
      "status": "completed",
      "trigger_type": "manual",
      "started_at": "2026-01-17T14:05:23Z",
      "completed_at": "2026-01-17T14:43:44Z",
      "duration_seconds": 2301,  // NEW
      "total_credits_used": 569,
      "current_stage": 7,
      "stages_completed": 7,  // NEW
      "stages_failed": 0,     // NEW
      "initial_snapshot": {
        "total_initial_items": 263
      },
      "summary": {  // NEW: quick summary
        "items_processed": 263,
        "items_created": 218,
        "content_created": 25,
        "images_generated": 24
      }
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_count": 47,
    "total_pages": 3
  }
}

---

Part 2: Automation Run Detail Page

Route & Access

Route: /automation/runs/:run_id
Access: Click on Run Title (e.g., "TechBlog.com #47") from Overview page

Current State Analysis

Available Data in AutomationRun Model

Core Fields:

• run_id: Unique identifier (e.g., run_20251203_140523_manual)
• status: running, paused, cancelled, completed, failed
• current_stage: 1-7 (current stage number)
• trigger_type: manual or scheduled
• started_at, completed_at, paused_at, resumed_at, cancelled_at
• total_credits_used: Total credits consumed

Initial Snapshot (captured at run start):

{
  "stage_1_initial": 150,
  "stage_2_initial": 10,
  "stage_3_initial": 50,
  "stage_4_initial": 25,
  "stage_5_initial": 15,
  "stage_6_initial": 8,
  "stage_7_initial": 5,
  "total_initial_items": 263
}

Stage Results (per stage):

// Stage 1: Keywords → Clusters
{
  "keywords_processed": 150,
  "clusters_created": 12,
  "batches": 3,
  "credits_used": 45,
  "time_elapsed": "00:03:24"
}

// Stage 2: Clusters → Ideas  
{
  "clusters_processed": 10,
  "ideas_created": 87,
  "credits_used": 120,
  "time_elapsed": "00:08:15"
}

// Stage 3: Ideas → Tasks
{
  "ideas_processed": 50,
  "tasks_created": 50,
  "credits_used": 0,
  "time_elapsed": "00:00:12"
}

// Stage 4: Tasks → Content
{
  "tasks_processed": 25,
  "content_created": 25,
  "total_words": 15450,
  "credits_used": 310,
  "time_elapsed": "00:18:42"
}

// Stage 5: Content → Image Prompts
{
  "content_processed": 15,
  "prompts_created": 45,
  "credits_used": 22,
  "time_elapsed": "00:02:15"
}

// Stage 6: Image Prompts → Images
{
  "images_processed": 8,
  "images_generated": 24,
  "credits_used": 72,
  "time_elapsed": "00:05:30"
}

// Stage 7: Review → Approved
{
  "ready_for_review": 5,
  "credits_used": 0,
  "time_elapsed": "00:00:03"
}

Current Issues

1. Automation Overview Page - Only shows recent 5 runs with minimal info:

   • Run ID, Status, Trigger Type, Date, Credits
   • No stage-level details
   • No breakdown of what was created/processed

2. Run History Widget - Limited to basic metrics

3. No Detail View - Users cannot drill down into a completed run to see:

   • What stages ran
   • What was processed at each stage
   • What was created/generated
   • Credits breakdown by stage
   • Time spent per stage
   • Initial vs final state comparison

Proposed Solution

1. New Page: Automation Run Detail (/automation/runs/:run_id)

Purpose: Provide comprehensive view of a single automation run with all stage details, metrics, and outcomes.

Route: /automation/runs/:run_id

Component: AutomationRunDetail.tsx

Page Layout

┌─────────────────────────────────────────────────────────────────┐
│ PageHeader                                                       │
│ ← Back to Overview                                              │
│ Run: run_20251203_140523_manual                                │
│ Badge: [Completed] • Trigger: Manual • Credits: 569           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Run Summary Card                                            │ │
│ │ ─────────────────────────────────────────────────────────── │ │
│ │ Started:  Dec 3, 2025 2:05 PM                              │ │
│ │ Duration: 38 minutes 21 seconds                            │ │
│ │ Status:   [✓ Completed]                                    │ │
│ │ Trigger:  Manual                                            │ │
│ │                                                              │ │
│ │ Total Items Processed: 263 → 218 items created            │ │
│ │ Total Credits Used:    569 credits                         │ │
│ │ Stages Completed:      7 of 7                              │ │
│ └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Pipeline Flow Visualization                                 │ │
│ │ ─────────────────────────────────────────────────────────── │ │
│ │                                                              │ │
│ │  150 → [Stage 1] → 12    87 → [Stage 4] → 25   45 → [Stage 6] → 24  │
│ │  Keywords  Clusters     Ideas   Content    Prompts  Images  │
│ │   (45 cr)               (310 cr)           (72 cr)         │
│ │                                                              │ │
│ │  10 → [Stage 2] → 87   15 → [Stage 5] → 45   5 → [Stage 7] → 5  │
│ │  Clusters   Ideas      Content  Prompts    Review  Approved │
│ │   (120 cr)             (22 cr)             (0 cr)          │
│ │                                                              │ │
│ │  50 → [Stage 3] → 50                                        │ │
│ │   Ideas     Tasks                                           │ │
│ │    (0 cr)                                                   │ │
│ └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Stage Details (Expandable Accordion)                        │ │
│ │ ─────────────────────────────────────────────────────────── │ │
│ │                                                              │ │
│ │ ▼ Stage 1: Keywords → Clusters         [✓ Completed] 45 cr │ │
│ │   ┌────────────────────────────────────────────────────┐  │ │
│ │   │ Input:     150 keywords                             │  │ │
│ │   │ Output:    12 clusters created                      │  │ │
│ │   │ Time:      3 minutes 24 seconds                     │  │ │
│ │   │ Credits:   45 credits                               │  │ │
│ │   │ Batches:   3 batches processed                      │  │ │
│ │   │                                                      │  │ │
│ │   │ Details:                                            │  │ │
│ │   │ • Processed 150 keywords in 3 batches              │  │ │
│ │   │ • Created 12 new clusters                          │  │ │
│ │   │ • Avg 4.4 keywords per cluster                     │  │ │
│ │   └────────────────────────────────────────────────────┘  │ │
│ │                                                              │ │
│ │ ▼ Stage 2: Clusters → Ideas           [✓ Completed] 120 cr │ │
│ │   ┌────────────────────────────────────────────────────┐  │ │
│ │   │ Input:     10 clusters                              │  │ │
│ │   │ Output:    87 ideas generated                       │  │ │
│ │   │ Time:      8 minutes 15 seconds                     │  │ │
│ │   │ Credits:   120 credits                              │  │ │
│ │   │                                                      │  │ │
│ │   │ Details:                                            │  │ │
│ │   │ • Processed 10 clusters                            │  │ │
│ │   │ • Generated 87 content ideas                       │  │ │
│ │   │ • Avg 8.7 ideas per cluster                        │  │ │
│ │   └────────────────────────────────────────────────────┘  │ │
│ │                                                              │ │
│ │ ▶ Stage 3: Ideas → Tasks              [✓ Completed] 0 cr   │ │
│ │ ▶ Stage 4: Tasks → Content            [✓ Completed] 310 cr │ │
│ │ ▶ Stage 5: Content → Image Prompts    [✓ Completed] 22 cr  │ │
│ │ ▶ Stage 6: Image Prompts → Images     [✓ Completed] 72 cr  │ │
│ │ ▶ Stage 7: Review → Approved          [✓ Completed] 0 cr   │ │
│ └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Credits Breakdown (Chart)                                   │ │
│ │ ─────────────────────────────────────────────────────────── │ │
│ │                                                              │ │
│ │  [Donut Chart showing credit distribution by stage]        │ │
│ │                                                              │ │
│ │  Stage 4: 54% (310 cr) - Content Generation               │ │
│ │  Stage 2: 21% (120 cr) - Idea Generation                  │ │
│ │  Stage 6: 13% (72 cr)  - Image Generation                 │ │
│ │  Stage 1: 8% (45 cr)   - Clustering                       │ │
│ │  Stage 5: 4% (22 cr)   - Image Prompts                    │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

2. Detail Page Design

Purpose: Provide comprehensive view of a single automation run with all stage details, metrics, and outcomes.

Route: /automation/runs/:run_id

Component: AutomationRunDetail.tsx

Page Layout

┌─────────────────────────────────────────────────────────────────────────────────┐
│ PageHeader                                                                       │
│ ← Back to Overview                                                              │
│ TechBlog.com #47                                                                │
│ run_20260117_140523_manual                                                      │
│ Badge: [✅ Completed] • Trigger: Manual • 569 credits used                      │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│ ┌──────────── RUN SUMMARY CARD ────────────────────────────────────────────────┐│
│ │                                                                               ││
│ │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         ││
│ │  │ Started     │  │ Duration    │  │ Status      │  │ Credits     │         ││
│ │  │ Jan 17      │  │ 38m 21s     │  │ ✅ Complete │  │ 569         │         ││
│ │  │ 2:05:23 PM  │  │             │  │ 7/7 stages  │  │             │         ││
│ │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘         ││
│ │                                                                               ││
│ │  Initial Queue: 263 items  →  Created: 218 items  →  Efficiency: 83%        ││
│ │                                                                               ││
│ └───────────────────────────────────────────────────────────────────────────────┘│
│                                                                                  │
│ ┌──────────── PIPELINE FLOW VISUALIZATION ─────────────────────────────────────┐│
│ │                                                                               ││
│ │  Stage 1         Stage 2         Stage 3         Stage 4                     ││
│ │  ┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐                 ││
│ │  │ 150 kw  │ ──▶ │ 10 clus │ ──▶ │ 50 idea │ ──▶ │ 25 task │                 ││
│ │  │   ↓     │     │   ↓     │     │   ↓     │     │   ↓     │                 ││
│ │  │ 12 clus │     │ 87 idea │     │ 50 task │     │ 25 cont │                 ││
│ │  │ 45 cr   │     │ 120 cr  │     │  0 cr   │     │ 310 cr  │                 ││
│ │  │ 3m 24s  │     │ 8m 15s  │     │ 12s     │     │ 18m 42s │                 ││
│ │  └─────────┘     └─────────┘     └─────────┘     └─────────┘                 ││
│ │                                                                               ││
│ │  Stage 5         Stage 6         Stage 7                                      ││
│ │  ┌─────────┐     ┌─────────┐     ┌─────────┐                                 ││
│ │  │ 15 cont │ ──▶ │ 8 promp │ ──▶ │ 5 revie │                                 ││
│ │  │   ↓     │     │   ↓     │     │   ↓     │                                 ││
│ │  │ 45 prom │     │ 24 img  │     │ 5 appro │                                 ││
│ │  │ 22 cr   │     │ 72 cr   │     │  0 cr   │                                 ││
│ │  │ 2m 15s  │     │ 5m 30s  │     │ 3s      │                                 ││
│ │  └─────────┘     └─────────┘     └─────────┘                                 ││
│ │                                                                               ││
│ └───────────────────────────────────────────────────────────────────────────────┘│
│                                                                                  │
│ ┌──────────── STAGE DETAILS (Expandable Accordion) ────────────────────────────┐│
│ │                                                                               ││
│ │ ▼ Stage 1: Keywords → Clusters              [✅ Completed]  45 credits       ││
│ │   ┌───────────────────────────────────────────────────────────────────────┐  ││
│ │   │ Processing Summary                                                     │  ││
│ │   │ ──────────────────────────────────────────────────────────────────── │  ││
│ │   │ Input:      150 keywords ready for clustering                         │  ││
│ │   │ Output:     12 clusters created                                       │  ││
│ │   │ Duration:   3 minutes 24 seconds                                      │  ││
│ │   │ Credits:    45 credits (0.3 cr/keyword)                              │  ││
│ │   │ Batches:    3 batches processed (50 keywords each)                   │  ││
│ │   │                                                                        │  ││
│ │   │ Efficiency Metrics                                                    │  ││
│ │   │ ──────────────────────────────────────────────────────────────────── │  ││
│ │   │ • Keywords per cluster: 12.5 avg                                     │  ││
│ │   │ • Cost efficiency: 3.75 credits per cluster                          │  ││
│ │   │ • Processing rate: 44 keywords/minute                                 │  ││
│ │   │                                                                        │  ││
│ │   │ Comparison to Historical Average (last 10 runs)                       │  ││
│ │   │ ──────────────────────────────────────────────────────────────────── │  ││
│ │   │ • Credits: 45 vs avg 42 (+7% ↑)                                      │  ││
│ │   │ • Output: 12 clusters vs avg 10 (+20% ↑ better yield)                │  ││
│ │   └───────────────────────────────────────────────────────────────────────┘  ││
│ │                                                                               ││
│ │ ▶ Stage 2: Clusters → Ideas               [✅ Completed]  120 credits        ││
│ │ ▶ Stage 3: Ideas → Tasks                  [✅ Completed]  0 credits          ││
│ │ ▶ Stage 4: Tasks → Content                [✅ Completed]  310 credits        ││
│ │ ▶ Stage 5: Content → Image Prompts        [✅ Completed]  22 credits         ││
│ │ ▶ Stage 6: Image Prompts → Images         [✅ Completed]  72 credits         ││
│ │ ▶ Stage 7: Review → Approved              [✅ Completed]  0 credits          ││
│ │                                                                               ││
│ └───────────────────────────────────────────────────────────────────────────────┘│
│                                                                                  │
│ ┌──────────── CREDITS BREAKDOWN (Donut Chart) ─────────────────────────────────┐│
│ │                                                                               ││
│ │     ┌───────────────┐      Stage 4: Content     54.5%  (310 cr)             ││
│ │     │   [DONUT]     │      Stage 2: Ideas       21.1%  (120 cr)             ││
│ │     │   CHART       │      Stage 6: Images      12.7%  (72 cr)              ││
│ │     │   569 cr      │      Stage 1: Clustering   7.9%  (45 cr)              ││
│ │     │   total       │      Stage 5: Prompts      3.9%  (22 cr)              ││
│ │     └───────────────┘      Stage 3,7: Free       0.0%  (0 cr)               ││
│ │                                                                               ││
│ │  💡 Insight: Content generation consumed most credits. Consider reducing     ││
│ │     word count targets or batching content tasks for better efficiency.      ││
│ │                                                                               ││
│ └───────────────────────────────────────────────────────────────────────────────┘│
│                                                                                  │
│ ┌──────────── RUN TIMELINE ────────────────────────────────────────────────────┐│
│ │                                                                               ││
│ │  2:05 PM ●─────────●─────────●─────────●─────────●─────────●─────────● 2:43  ││
│ │          │         │         │         │         │         │         │       ││
│ │       Started   Stage 2   Stage 3   Stage 4   Stage 5   Stage 6  Completed  ││
│ │       Stage 1   +3m 24s   +11m 39s  +11m 51s  +30m 33s  +32m 48s  +38m 21s  ││
│ │                                                                               ││
│ └───────────────────────────────────────────────────────────────────────────────┘│
│                                                                                  │
│ ┌──────────── ACTIONS ─────────────────────────────────────────────────────────┐│
│ │                                                                               ││
│ │  [📋 View Logs]  [📊 Export Report]  [🔄 Re-run Similar]                     ││
│ │                                                                               ││
│ └───────────────────────────────────────────────────────────────────────────────┘│
│                                                                                  │
└─────────────────────────────────────────────────────────────────────────────────┘

---

Part 3: Component Architecture

New Components to Create:

Overview Page Components:

1. RunStatisticsSummary.tsx - Top stats cards

   • Total runs, success rate, avg duration, avg credits
   • Trend indicators (week-over-week)

2. PredictiveCostAnalysis.tsx - Predictive cost panel

   • Stage-by-stage pending items and estimates
   • Historical average rates per stage
   • Expected outputs calculation
   • Attention items (skipped/failed)

3. EnhancedRunHistory.tsx - Improved history table

   • Clickable run titles (Site Name #N)
   • Stage progress badges
   • Duration display
   • Quick summary stats

Detail Page Components:

4. AutomationRunDetail.tsx - Main detail page

   • Fetches full run data by run_id
   • Displays all sections outlined above

5. RunSummaryCard.tsx - Summary overview

   • Status, duration, totals
   • Quick metrics with icons

6. PipelineFlowVisualization.tsx - Visual flow diagram

   • Shows stage connections with arrows
   • Input/output counts
   • Credits and duration per stage

7. StageAccordion.tsx - Expandable stage details

   • Collapsible accordion for each stage
   • Stage-specific metrics
   • Historical comparison
   • Efficiency metrics

8. CreditBreakdownChart.tsx - Credit distribution

   • Donut/pie chart (using recharts)
   • Stage-by-stage breakdown with legend
   • AI-generated insights

9. RunTimeline.tsx - Horizontal timeline

   • Visual stage progression
   • Time markers

10. StageProgressBadges.tsx - Compact stage indicators

    • Used in run history table
    • Visual status for each stage (✓, ✗, ●, ○)

---

Part 4: API Enhancements

New Endpoint: Overview Statistics

Endpoint: GET /api/v1/automation/overview_stats/?site_id=xxx

Implementation in automation/views.py:

@extend_schema(tags=['Automation'])
@action(detail=False, methods=['get'])
def overview_stats(self, request):
    """
    GET /api/v1/automation/overview_stats/?site_id=123
    Get comprehensive automation statistics for overview page
    """
    site, error_response = self._get_site(request)
    if error_response:
        return error_response
    
    # Calculate run statistics from last 30 days
    thirty_days_ago = timezone.now() - timedelta(days=30)
    seven_days_ago = timezone.now() - timedelta(days=7)
    fourteen_days_ago = timezone.now() - timedelta(days=14)
    
    all_runs = AutomationRun.objects.filter(site=site)
    recent_runs = all_runs.filter(started_at__gte=thirty_days_ago)
    this_week_runs = all_runs.filter(started_at__gte=seven_days_ago)
    last_week_runs = all_runs.filter(started_at__gte=fourteen_days_ago, started_at__lt=seven_days_ago)
    
    completed_runs = recent_runs.filter(status='completed')
    failed_runs = recent_runs.filter(status='failed')
    
    # Calculate averages from completed runs
    avg_duration = completed_runs.annotate(
        duration=F('completed_at') - F('started_at')
    ).aggregate(avg=Avg('duration'))['avg']
    
    avg_credits = completed_runs.aggregate(avg=Avg('total_credits_used'))['avg'] or 0
    
    # Calculate historical averages per stage
    historical_averages = self._calculate_historical_averages(site, completed_runs)
    
    # Get pending items and calculate predictions
    predictive_analysis = self._calculate_predictive_analysis(site, historical_averages)
    
    # Get attention items (failed/skipped)
    attention_items = self._get_attention_items(site)
    
    return Response({
        'run_statistics': {
            'total_runs': all_runs.count(),
            'completed_runs': completed_runs.count(),
            'failed_runs': failed_runs.count(),
            'success_rate': round(completed_runs.count() / recent_runs.count() * 100, 1) if recent_runs.count() > 0 else 0,
            'avg_duration_seconds': avg_duration.total_seconds() if avg_duration else 0,
            'avg_credits_per_run': round(avg_credits, 1),
            'runs_this_week': this_week_runs.count(),
            'runs_last_week': last_week_runs.count(),
        },
        'predictive_analysis': predictive_analysis,
        'attention_items': attention_items,
        'historical_averages': historical_averages,
    })

New Endpoint: Run Detail

Endpoint: GET /api/v1/automation/run_detail/?run_id=xxx

Response:

{
  run: {
    run_id: string;
    run_number: number;
    run_title: string;
    site_name: string;
    status: string;
    trigger_type: string;
    current_stage: number;
    started_at: string;
    completed_at: string | null;
    paused_at: string | null;
    resumed_at: string | null;
    cancelled_at: string | null;
    duration_seconds: number;
    total_credits_used: number;
    error_message: string | null;
  },
  initial_snapshot: {
    stage_1_initial: number;
    stage_2_initial: number;
    stage_3_initial: number;
    stage_4_initial: number;
    stage_5_initial: number;
    stage_6_initial: number;
    stage_7_initial: number;
    total_initial_items: number;
  },
  stages: [
    {
      number: 1,
      name: "Keywords → Clusters",
      status: "completed" | "running" | "pending" | "skipped" | "failed",
      is_enabled: boolean,
      result: {
        input_count: number;
        output_count: number;
        credits_used: number;
        time_elapsed: string;
        batches?: number;
        // Stage-specific fields
        keywords_processed?: number;
        clusters_created?: number;
        ideas_created?: number;
        tasks_created?: number;
        content_created?: number;
        total_words?: number;
        prompts_created?: number;
        images_generated?: number;
      },
      efficiency: {
        cost_per_input: number;
        cost_per_output: number;
        output_ratio: number;
        processing_rate: number;  // items per minute
      },
      comparison: {
        avg_credits: number;
        avg_output: number;
        credits_diff_percent: number;
        output_diff_percent: number;
      }
    },
    // ... stages 2-7
  ],
  metrics: {
    total_input_items: number;
    total_output_items: number;
    duration_seconds: number;
    efficiency_percent: number;
    credits_by_stage: {
      stage_1: number;
      stage_2: number;
      stage_3: number;
      stage_4: number;
      stage_5: number;
      stage_6: number;
      stage_7: number;
    };
    time_by_stage: {
      stage_1: number;  // seconds
      stage_2: number;
      // ...
    };
  },
  insights: string[];  // AI-generated insights about the run
}

Enhanced History Endpoint

Update: GET /api/v1/automation/history/?site_id=xxx

Add run numbers, titles, and summaries:

{
  runs: [
    {
      run_id: string;
      run_number: number;
      run_title: string;
      status: string;
      trigger_type: string;
      started_at: string;
      completed_at: string | null;
      duration_seconds: number;
      total_credits_used: number;
      current_stage: number;
      stages_completed: number;
      stages_failed: number;
      initial_snapshot: { 
        total_initial_items: number;
      };
      summary: {
        items_processed: number;
        items_created: number;
        content_created: number;
        images_generated: number;
      };
      stage_statuses: string[];  // ['completed', 'completed', 'completed', 'failed', 'skipped', 'skipped', 'skipped']
    }
  ],
  pagination: {
    page: number;
    page_size: number;
    total_count: number;
    total_pages: number;
  }
}

---

Part 5: Implementation Phases

Phase 1: Backend API Enhancement (4-5 hours) ✅ COMPLETED

Status: COMPLETED
Implementation Date: January 2025
File: /backend/igny8_core/business/automation/views.py

Completed Tasks:

1. ✅ Helper Methods Implemented:

   • _calculate_run_number(site, run) - Sequential numbering per site based on started_at timestamp
   • _calculate_historical_averages(site, completed_runs) - Analyzes last 10 completed runs (minimum 3 required), calculates per-stage averages and overall metrics
   • _calculate_predictive_analysis(site, historical_averages) - Queries pending items, estimates credits and outputs for next run
   • _get_attention_items(site) - Counts skipped ideas, failed content, failed images

2. ✅ New Endpoint: overview_stats

   • Route: GET /api/v1/automation/overview_stats/
   • Returns: run_statistics (8 metrics), predictive_analysis (7 stages + totals), attention_items, historical_averages (10 fields)
   • Features: 30-day trends, 7-day average duration, variance calculations

3. ✅ Enhanced Endpoint: history

   • Route: GET /api/v1/automation/history/?page=1&page_size=20
   • Added: run_number, run_title (format: "{site.domain} #{run_number}"), duration_seconds, stages_completed, stages_failed, initial_snapshot, summary (items_processed/created/content/images), stage_statuses array
   • Features: Pagination support, per-run stage status tracking

4. ✅ New Endpoint: run_detail

   • Route: GET /api/v1/automation/run_detail/?run_id=abc123
   • Returns: Full run info, 7 stages with detailed analysis, efficiency metrics (credits_per_item, items_per_minute, credits_per_minute), historical comparison, auto-generated insights
   • Features: Variance detection, failure alerts, efficiency comparisons

Technical Notes:

• All queries scoped to site and account for multi-tenancy security
• Historical averages use last 10 completed runs with 3-run minimum fallback
• Division by zero handled gracefully with defaults
• Stage status logic: pending → running → completed/failed/skipped
• Run numbers calculated via count-based approach for legacy compatibility

Phase 2: Frontend Overview Page (4-5 hours) ✅ COMPLETED

Status: COMPLETED
Implementation Date: January 17, 2026
Files Created: 4 new components, 1 page updated

Completed Components:

1. ✅ RunStatisticsSummary.tsx - Displays run metrics with icons and trends
2. ✅ PredictiveCostAnalysis.tsx - Donut chart with stage breakdown and confidence
3. ✅ AttentionItemsAlert.tsx - Warning banner for failed/skipped items
4. ✅ EnhancedRunHistory.tsx - Clickable table with pagination and stage icons
5. ✅ Updated AutomationOverview.tsx - Integrated all new components

Phase 3: Frontend Detail Page (5-6 hours) ✅ COMPLETED

Status: COMPLETED
Implementation Date: January 17, 2026
Files Created: 1 page + 5 components + supporting files

Completed Components:

1. ✅ AutomationRunDetail.tsx - Main detail page with routing
2. ✅ RunSummaryCard.tsx - Run header with key metrics
3. ✅ StageAccordion.tsx - Expandable stage details with comparisons
4. ✅ EfficiencyMetrics.tsx - Performance metrics card
5. ✅ InsightsPanel.tsx - Auto-generated insights display
6. ✅ CreditBreakdownChart.tsx - ApexCharts donut visualization

Supporting Files:

• ✅ types/automation.ts - TypeScript definitions (12 interfaces)
• ✅ utils/dateUtils.ts - Date formatting utilities
• ✅ Updated automationService.ts - Added 3 API methods
• ✅ Updated App.tsx - Added /automation/runs/:runId route
• ✅ Updated icons/index.ts - Added ExclamationTriangleIcon

Phase 4: Polish & Testing (3-4 hours) ⏳ IN PROGRESS

Remaining Tasks:

1. Error handling and loading states (partially done)
2. Empty states for no data (partially done)
3. Mobile responsiveness testing
4. Dark mode verification
5. Accessibility improvements (ARIA labels)
6. Unit tests for new components

Total Estimated Time: 16-20 hours
Actual Time Spent: ~12 hours (Phases 1-3)
Remaining: ~3-4 hours (Phase 4)

---

Part 6: User Benefits

Immediate Benefits:

1. Transparency - See exactly what happened in each run, no black box
2. Cost Predictability - Know expected costs BEFORE running automation
3. Performance Tracking - Monitor run duration and efficiency trends
4. Troubleshooting - Quickly identify bottlenecks or failed stages
5. ROI Validation - Concrete output metrics (content created, images generated)

Strategic Benefits:

6. Credit Budget Planning - Historical averages help plan monthly budgets
7. Optimization Insights - Identify which stages consume most resources
8. Confidence Building - Predictive analysis reduces uncertainty
9. Proactive Management - Attention items surface problems early
10. Historical Context - Compare current run to past performance

---

Part 7: Success Metrics

Engagement Metrics:

• % of users viewing run details (target: 60%+ of active automation users)
• Time spent on detail page (indicates value - target: 30+ seconds avg)
• Click-through rate on predictive cost analysis (target: 40%+)

Business Metrics:

• Reduced support tickets about "what did automation do?" (target: 50% reduction)
• Increased automation run frequency (users trust the system more)
• Better credit budget accuracy (users run out less often)

User Satisfaction:

• NPS improvement for automation feature (target: +10 points)
• User feedback survey ratings (target: 4.5+ out of 5)

---

Part 8: Technical Considerations

Performance

• Cache run details for completed runs (rarely change)
• Paginate run history (20 per page, lazy load)
• Lazy load stage details (accordion pattern)
• Calculate historical averages server-side with efficient queries

Data Integrity

• Handle incomplete runs gracefully (show partial data)
• Show "N/A" for skipped/disabled stages
• Ensure all stage results are properly saved during automation
• Validate snapshot data before displaying

Accessibility

• Proper ARIA labels for charts and interactive elements
• Keyboard navigation for accordion
• Screen reader support for status badges
• High contrast mode support for visualizations

Mobile Responsiveness

• Stack cards vertically on mobile
• Horizontal scroll for pipeline visualization
• Collapsible sections by default on mobile
• Touch-friendly accordion interactions

---

Part 9: Future Enhancements (Post-MVP)

High Priority:

1. Run Comparison - Compare two runs side-by-side
2. Export Reports - Download run details as PDF/CSV
3. Retry Failed Stage - Ability to retry specific failed stage
4. Real-time Updates - WebSocket for live run progress

Medium Priority:

5. Scheduled Run Calendar - View upcoming scheduled runs
6. Stage-Level Logs - View detailed logs per stage (expandable)
7. Error Details - Expanded error information for failed runs
8. Run Tags/Notes - Add custom notes to runs for tracking

Nice to Have:

9. Cost Alerts - Notify when predicted cost exceeds threshold
10. Efficiency Recommendations - AI-powered suggestions
11. Trend Charts - Historical graphs of costs/outputs over time
12. Bulk Operations - Select and compare multiple runs

---

Conclusion

This enhanced plan transforms the Automation Overview page from a basic dashboard into a comprehensive command center that provides:

1. Historical Insights - Run statistics, success rates, and trends
2. Predictive Intelligence - Cost estimates and expected outputs based on actual data
3. Actionable Alerts - Surface items needing attention
4. Deep-Dive Capability - Click through to full run details

The Run Detail page provides complete transparency into every automation run, helping users understand exactly what happened, how efficient it was compared to historical averages, and where their credits went.

Combined, these improvements will significantly increase user confidence in the automation system, reduce support burden, and help users optimize their content production workflow.