# 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 displaying detailed automation run information to users, providing transparency into what was processed, what was created, and how credits were consumed.

## 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):**
```json
{
  "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):**
```json
// 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. Enhanced Automation Overview Page

**Update:** `/automation/overview`

#### Add "View Details" Links to Run History Table

**Current:**
```
Run ID | Status | Type | Date | Credits
```

**Enhanced:**
```
Run ID | Status | Type | Date | Credits | Actions
                                          [View Details →]
```

#### Update Table to Show Stage Progress Indicators

**Visual Stage Progress:**
```
Run ID: run_20251203_140523_manual
Status: Completed
Stages: [✓][✓][✓][✓][✓][✓][✓] 7/7 completed
Credits: 569
[View Details →]
```

For running runs:
```
Run ID: run_20251203_150000_manual  
Status: Running
Stages: [✓][✓][✓][●][ ][ ][ ] 4/7 in progress
Credits: 387
[View Live Progress →]
```

### 3. Quick Stats Cards at Top of Overview

**Add 3 new metric cards:**

```
┌────────────────────────┐ ┌────────────────────────┐ ┌────────────────────────┐
│ Last 7 Days           │ │ Items Processed        │ │ Avg Credits/Run       │
│ 12 runs               │ │ 1,847 total           │ │ 486 credits          │
│ +3 from prev week     │ │ 634 content created   │ │ ↓ 12% from last week │
└────────────────────────┘ └────────────────────────┘ └────────────────────────┘
```

### 4. Component Architecture

#### New Components to Create:

1. **`AutomationRunDetail.tsx`** - Main detail page
   - Fetches full run data by run_id
   - Displays all sections outlined above
   
2. **`RunSummaryCard.tsx`** - Summary overview
   - Status, duration, totals
   - Quick metrics
   
3. **`PipelineFlowVisualization.tsx`** - Visual flow diagram
   - Shows stage connections
   - Input/output counts
   - Credits per stage
   
4. **`StageAccordion.tsx`** - Expandable stage details
   - Collapsible accordion for each stage
   - Stage-specific metrics
   - Processing details
   
5. **`CreditBreakdownChart.tsx`** - Credit distribution
   - Donut/pie chart
   - Stage-by-stage breakdown
   
6. **`StageProgressBadges.tsx`** - Compact stage indicators
   - Used in run history table
   - Visual status for each stage

### 5. API Enhancements Needed

#### New Endpoint: Get Run Detail

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

**Response:**
```typescript
{
  run: {
    run_id: 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;
    total_credits_used: number;
    error_message: string | null;
  },
  initial_snapshot: {
    stage_1_initial: number;
    stage_2_initial: number;
    ...
    total_initial_items: number;
  },
  stages: [
    {
      number: 1,
      name: "Keywords → Clusters",
      status: "completed" | "running" | "pending" | "skipped",
      result: {
        keywords_processed: 150,
        clusters_created: 12,
        batches: 3,
        credits_used: 45,
        time_elapsed: "00:03:24"
      }
    },
    ...
  ],
  metrics: {
    total_input_items: number;
    total_output_items: number;
    duration_seconds: number;
    credits_by_stage: { [stage: string]: number };
  }
}
```

#### Enhanced History Endpoint

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

Add `initial_snapshot` and `completed_stages` to each run:

```typescript
{
  runs: [
    {
      run_id: string;
      status: string;
      trigger_type: string;
      started_at: string;
      completed_at: string | null;
      total_credits_used: number;
      current_stage: number;
      completed_stages: number; // NEW: Count of completed stages
      initial_snapshot: { total_initial_items: number }; // NEW
    }
  ]
}
```

## Implementation Phases

### Phase 1: Backend API Enhancement (2-3 hours)
1. Create `run_detail` endpoint in `automation/views.py`
2. Add stage result parsing logic
3. Calculate metrics and breakdown
4. Test with existing runs

### Phase 2: Frontend Components (4-5 hours)
1. Create new detail page route
2. Build `AutomationRunDetail` page component
3. Create sub-components (cards, accordion, chart)
4. Add TypeScript types

### Phase 3: Enhanced Overview (2-3 hours)
1. Add "View Details" links to history table
2. Add stage progress badges
3. Update quick stats cards
4. Link to detail page

### Phase 4: Polish & Testing (2 hours)
1. Error handling
2. Loading states
3. Empty states
4. Mobile responsiveness
5. Dark mode support

**Total Estimated Time: 10-13 hours**

## User Benefits

1. **Transparency** - See exactly what happened in each run
2. **Cost Analysis** - Understand where credits are being spent
3. **Performance Tracking** - Monitor run duration and efficiency
4. **Troubleshooting** - Identify bottlenecks or failed stages
5. **Historical Context** - Compare runs over time
6. **ROI Validation** - See concrete output (content created, images generated)

## Success Metrics

1. User engagement with detail view (% of users viewing details)
2. Time spent on detail page (indicates value)
3. Reduced support queries about "what did automation do?"
4. Increased confidence in automation (measured via survey/NPS)
5. Better credit budget planning (users can predict costs)

## Technical Considerations

### Performance
- Cache run details (rarely change after completion)
- Paginate run history if list grows large
- Lazy load stage details (accordion pattern)

### Data Integrity
- Ensure all stage results are properly saved
- Handle incomplete runs gracefully
- Show "N/A" for skipped/disabled stages

### Accessibility
- Proper ARIA labels for charts
- Keyboard navigation for accordion
- Screen reader support for status badges

## Future Enhancements (Post-MVP)

1. **Run Comparison** - Compare two runs side-by-side
2. **Export Reports** - Download run details as PDF/CSV
3. **Scheduled Run Calendar** - View upcoming scheduled runs
4. **Cost Projections** - Predict next run costs based on current queue
5. **Stage-Level Logs** - View detailed logs per stage
6. **Error Details** - Expanded error information for failed runs
7. **Retry Failed Stage** - Ability to retry specific failed stage
8. **Run Tags/Notes** - Add custom notes to runs for tracking

## Conclusion

The AutomationRun model contains rich data that can provide immense value to users. By creating a comprehensive detail view and enhancing the overview page, we transform raw data into actionable insights. This improves transparency, builds trust, and helps users optimize their automation strategy and credit usage.