docs re-org

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

@@ -0,0 +1,149 @@
+# 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.