igny8/docs/30-FRONTEND/automation/AUTOMATION-UI.md

Automation Frontend Module

Location: frontend/src/pages/automation/
Purpose: UI components and pages for automation module

Source Files

Automation Page (AI Automation Pipeline Dashboard)

Purpose

Provide a site-scoped dashboard to configure, run, pause, resume, and monitor the 7-stage automation pipeline. Surfaces pipeline overview, current run status, metrics, history, configuration modal, and credit sufficiency checks.

Code Locations (exact paths)

• Primary page: frontend/src/pages/Automation/AutomationPage.tsx
• Service: frontend/src/services/automationService (config, current run, estimate, pipeline overview, runNow, pause, resume, publishWithoutReview)
• Metrics sources: frontend/src/services/api (fetchKeywords, fetchClusters, fetchContentIdeas, fetchTasks, fetchContent, fetchContentImages)
• UI components: frontend/src/components/Automation/{ActivityLog,ConfigModal,RunHistory,CurrentProcessingCard}, frontend/src/components/dashboard/EnhancedMetricCard, frontend/src/components/common/ComponentCard, frontend/src/components/common/PageMeta, frontend/src/components/common/DebugSiteSelector

High-Level Responsibilities

• Load automation config, current run, credit estimate, and pipeline overview for the active site.
• Poll current run and pipeline status while running/paused; refresh metrics regularly during runs.
• Provide controls: Run Now, Pause, Resume, Save Config, Publish Without Review.
• Show per-stage cards, current processing card, run history, and activity log.

Detailed Behavior

• Site binding: requires useSiteStore.activeSite; without it, page shows a “select a site” message.
• Initial load (loadData): parallel calls to getConfig, getCurrentRun, estimate, getPipelineOverview plus low-level metrics (keywords/clusters/ideas/tasks/content/images counts) per site_id.
• Polling: 5s interval; if run status is running/paused, refresh run, pipeline, and metrics; otherwise refresh pipeline only.
• Metrics: counts for keywords (total/new/mapped), clusters (total/new/mapped), ideas (total/new/queued/completed), tasks (total), content (total/draft/review/published), images (total/pending).
• Stage cards: derived from STAGE_CONFIG array representing 7 pipeline stages including manual review gate.
• Actions:
  • Run Now: checks credit sufficiency from estimate; blocks if insufficient.
  • Pause/Resume: call automationService with site + run_id, then refresh run/pipeline/metrics.
  • Save Config: persists partial config, updates local state, reloads pipeline/metrics/run.
  • Publish Without Review: calls publishWithoutReview with confirmation prompt, then reloads.
• UI states: loading spinner until initial fetch; showProcessingCard toggled on when a run exists.

Data Structures / Models Involved (no code)

• AutomationConfig: site-level automation settings (intervals, gates, etc.).
• AutomationRun: run_id, status (running, paused, etc.), stage info.
• PipelineStage: stage list with status/progress.
• Metrics DTOs from planner/writer/image endpoints (count fields only).

Execution Flow

• useEffect with site dependency → loadData.
• Interval polling while active runs → loadCurrentRun, loadPipelineOverview, loadMetrics.
• User actions dispatch to automationService; toasts for success/error; follow-up refreshes.

Cross-Module Interactions

• Pulls planner/writer/image counts to present authoritative pipeline context.
• Uses useSiteStore for tenant/site scoping; credit checks rely on billing estimate API.

State Transitions

• currentRun.status drives polling and control availability.
• showProcessingCard turns on when a run exists.
• estimate.sufficient gates Run Now action.

Error Handling

• Toast-based error reporting; fetch failures log to console but keep page usable.
• Metrics fetch wrapped in try/catch; failure degrades to missing metrics without blocking the rest.

Tenancy Rules

• All automation service calls require activeSite.id; backend enforces account/site scoping. No client override for other tenants.

Billing Rules (if applicable)

• Run Now is blocked when estimate.sufficient is false; shows required vs current credits.

Background Tasks / Schedulers (if applicable)

• Client-side polling (5s) during active runs; no background scheduling beyond that.

Key Design Considerations

• Polling keeps UI aligned with long-running Celery pipeline states.
• Credit gate prevents user-initiated runs that would immediately fail server-side.
• Metrics are read-only mirrors of backend aggregates to align UI with planner/writer state.

How Developers Should Work With This Module

• When adding new stages, extend STAGE_CONFIG and ensure backend pipeline overview includes them.
• Keep polling interval modest; if adding heavier metrics, consider staggering fetches to avoid rate limits.
• Wire new config fields through AutomationConfig type, ConfigModal, and updateConfig payload.

Automation Components

Purpose

Describe the reusable UI components that compose the automation dashboard: stage cards, current processing card, run history, activity log, and configuration modal. These components visualize pipeline state, history, and settings sourced from automation services.

Code Locations (exact paths)

• Stage cards & layout: frontend/src/pages/Automation/AutomationPage.tsx (renders stage cards from STAGE_CONFIG)
• Current run card: frontend/src/components/Automation/CurrentProcessingCard.tsx
• Activity log: frontend/src/components/Automation/ActivityLog.tsx
• Run history: frontend/src/components/Automation/RunHistory.tsx
• Config modal: frontend/src/components/Automation/ConfigModal.tsx
• Shared UI: frontend/src/components/common/{ComponentCard,PageMeta,DebugSiteSelector}, frontend/src/components/dashboard/EnhancedMetricCard

High-Level Responsibilities

• Stage cards: show each of the 7 pipeline stages with icon/color/status derived from pipeline overview.
• CurrentProcessingCard: surface active run details, stage name, status, percent, timestamps, and controls (Pause/Resume).
• ActivityLog: list recent automation events (from run log feed).
• RunHistory: show prior runs with status and timestamps.
• ConfigModal: edit and persist automation configuration per site.

Detailed Behavior

• Stage Cards:
  • Built from STAGE_CONFIG array (keywords→clusters, clusters→ideas, ideas→tasks, tasks→content, content→image prompts, image prompts→images, manual review).
  • Status/progress comes from pipelineOverview.stages provided by automationService.getPipelineOverview.
• CurrentProcessingCard:
  • Receives currentRun and shows status; displays pause/resume buttons wired to page handlers that call automationService.pause/resume.
  • Hidden when no current run; toggled by showProcessingCard.
• RunHistory:
  • Takes run list (from automationService.getCurrentRun payload history) and renders chronological entries.
• ActivityLog:
  • Displays textual log entries for the active run; consumes run log data supplied by the page.
• ConfigModal:
  • Opens from page button; on save calls automationService.updateConfig(activeSite.id, newConfig); merges into local config and refreshes pipeline/metrics.

Data Structures / Models Involved (no code)

• AutomationRun (id, status, stage, progress, started_at/ended_at).
• PipelineStage array with stage identifiers, names, progress.
• AutomationConfig fields shown in modal (intervals/gates/etc., defined server-side).

Execution Flow

• Page loads run + pipeline → passes data into stage cards, processing card, history, activity log.
• User opens ConfigModal → submit triggers updateConfig → page reloads pipeline/metrics/run to reflect new settings.
• Pause/Resume buttons on CurrentProcessingCard call page handlers, which in turn call automationService.

Cross-Module Interactions

• Components depend on site context from useSiteStore and data from automationService; no direct planner/writer calls (metrics happen in page).

State Transitions

• Components are pure renderers; state (visibility, selected config) managed by AutomationPage.

Error Handling

• Errors in save/pause/resume are surfaced by the page via toasts; components render based on provided props.

Tenancy Rules

• All data passed in is already scoped to activeSite; components do not alter scoping.

Billing Rules (if applicable)

• None inside components; Run Now credit gating handled at page level.

Background Tasks / Schedulers (if applicable)

• None; updates driven by page polling interval.

Key Design Considerations

• Separation of concerns: components stay presentational; network calls remain in page.
• Stage cards use color/icon metadata for fast visual scanning of pipeline status.

How Developers Should Work With This Module

• Add new stages by extending STAGE_CONFIG and ensuring pipeline overview includes the new stage id/status.
• Extend ConfigModal fields in sync with backend AutomationConfig; persist via automationService.
• Keep CurrentProcessingCard controls minimal; any new action should call automationService and refresh run/pipeline afterward.