TrueGrowth/openspec/changes/add-visual-business-orchestration/design.md

Context

TrueGrowth already has the pieces needed for business automation: a React/Nx workbench shell, a local runtime API, task records, assets, provider routing, ComfyUI/AIGCPanel image and video generation bridges, FunClip/FFmpeg sidecar readiness, Agent-Reach intelligence work, and a native social publishing workspace.

The missing product layer is a native visual business orchestration system that lets users connect these capabilities without leaving TrueGrowth. The editor should feel like a professional desktop workbench, not a generic open-source automation console embedded into the app.

Goals

• Provide a visual drag-and-connect DAG editor for business workflows.
• Replace the current simple stage-list workflow page behind /workflow with the new editor while preserving the existing navigation and App Center entry.
• Support configurable nodes for news/intelligence, image, video, digital human, intelligent editing, publishing, transforms, conditions, and approvals.
• Execute workflows with deterministic dependency ordering, per-node state, progress, retries, cancellation, and resumable run records.
• Provide a scheduled task center for recurring and one-off automation.
• Reuse TrueGrowth's existing providers, local tasks, assets, publish adapters, and runtime bridges.
• Keep the architecture small enough to own inside TrueGrowth while allowing future provider adapters.

Non-Goals

• Do not embed n8n, Node-RED, Activepieces, or a foreign automation UI as the main product surface.
• Do not replace the existing AI image, AI video, digital-human, intelligent editing, intelligence, task center, or publish center pages.
• Do not store raw social account cookies or provider secrets in frontend workflow definitions.
• Do not require cloud services for the first release.

Open-Source Capability Assessment

• React Flow is the best fit for the editor canvas: node/edge rendering, drag interactions, custom nodes, minimap, controls, and fit-view behavior match the required visual DAG editing surface.
• XState is useful for node/run lifecycle modeling, but it should stay at the workflow runtime state-boundary rather than driving the entire React page.
• p-queue is a good fit for bounded local concurrency, per-provider queues, and platform rate limiting.
• Croner is a good fit for cron expressions, next-run calculations, timezone handling, and local scheduled triggers.
• SQLite is the right durable store for desktop/local runtime persistence, but implementation can start behind a repository interface so development may use the current JSON/local runtime store until the SQLite dependency is wired.
• Electron UtilityProcess is appropriate for heavy or fragile sidecars such as FFmpeg/FunClip/ASR/browser publishing once the Electron shell is packaging these flows. Browser/PWA development should keep using the local runtime API boundary.
• Full automation platforms such as n8n, Node-RED, Windmill, Temporal, or Activepieces are better as references or optional future executors than as the first embedded runtime. Their UI, credential model, plugin model, and deployment assumptions do not match TrueGrowth's asset/provider/publish-center workflow closely enough.

Recommended Architecture

Frontend Editor

• Reuse the existing /workflow route and 流程编排 navigation/App Center entry.
• Use React Flow for the main canvas.
• Keep a wide left node palette, central canvas, right inspector, bottom run/log drawer, and top toolbar for save, validate, run, schedule, duplicate, export, and history.
• Store editor documents as WorkflowDefinition records with nodes, edges, viewport, metadata, version, and validation status.
• Keep UI aligned with the TrueGrowth Aurora-style direction: left navigation, compact bordered white cards, 40-42px controls, orange primary actions, short Chinese labels, and no raw technical/demo copy.

Existing Workflow Migration

• Treat the current WorkflowPage and WORKFLOW_PRESETS stage-list model as the legacy implementation.
• Preserve the visible /workflow route, left navigation item, and App Center card.
• Convert any useful preset examples into real graph templates with nodes and edges.
• Remove or hide the old linear-stage UI once the React Flow editor can create, save, validate, run, and schedule workflows.
• Keep existing local runtime /local-api/workflows/run compatibility as one adapter path, not as the whole orchestration model.

Node Model

Each node definition should include:

• id, type, label, position
• inputs, outputs, and media/data contracts
• configSchema and config
• providerRef when the node calls a model/runtime/provider
• retry, timeoutMs, concurrencyKey, and resourceHints
• secretsRef for runtime-owned credentials
• ui metadata for icon, accent, collapsed summary, and inspector sections

Initial node groups:

• 输入: manual input, scheduled trigger, news/intelligence query, asset picker, webhook/API placeholder
• 生成: AI image, AI video, digital-human video, voice/TTS
• 处理: intelligent edit, ASR, subtitle, FFmpeg transform, format conversion, merge/split
• 决策: condition, switch, filter, approval gate
• 输出: save asset, publish campaign, notification/webhook placeholder
• 工具: prompt template, variable mapper, delay, script transform placeholder

Runtime Engine

Implement a lightweight DAG engine in the local runtime:

• Validate acyclic graph and topologically sort runnable nodes.
• Track node states: idle, queued, running, waiting, succeeded, failed, skipped, cancelled.
• Track run states: draft, queued, running, waiting, succeeded, failed, partial, cancelled.
• Resolve inputs from upstream node outputs, run variables, selected assets, and schedule payloads.
• Dispatch node execution to provider adapters through existing local runtime endpoints where possible.
• Use p-queue for global concurrency, per-provider concurrency, and per-platform publishing limits.
• Emit structured events for run started, node queued, node progress, node log, node output, node failed, run completed, and run cancelled.
• Persist state before and after each node transition to support recovery.

State Machines

Use XState for explicit runtime lifecycle state machines:

• Workflow run lifecycle: queued -> running -> waiting/succeeded/failed/partial/cancelled.
• Node lifecycle: idle -> queued -> running -> waiting -> succeeded/failed/skipped/cancelled.
• Schedule lifecycle: disabled -> armed -> firing -> backoff/armed.

XState should model lifecycle and recovery semantics; dependency resolution remains in the DAG engine.

Scheduling

Use Croner for recurring and one-off schedules:

• Support cron expression, simple presets, timezone, start/end date, misfire policy, overlap policy, and max active runs.
• Show next run time preview in the UI.
• Store scheduled task definitions separately from workflow definitions so the same workflow can have multiple schedules.
• Each scheduled fire creates an immutable WorkflowRun with trigger metadata.
• Support manual "run now" for any active schedule.

Persistence

Use a storage repository interface with these conceptual tables/collections:

• workflow_definitions
• workflow_versions
• workflow_schedules
• workflow_runs
• workflow_node_runs
• workflow_run_events
• workflow_artifacts
• workflow_locks

SQLite should become the desktop/local runtime durable implementation. During incremental development, the current local runtime JSON store may be used only behind the same repository API.

Provider and Adapter Boundaries

• Image/video generation nodes call existing provider routing, ComfyUI, AIGCPanel, or canvas generation bridges.
• Digital-human nodes call the existing digital-human runtime path and produce video assets.
• Intelligent editing nodes call FunClip, FFmpeg, ASR, and subtitle tools through the sidecar bridge.
• Publish nodes create native social publishing campaigns and track per-target status through the existing publishing adapter.
• Intelligence/news nodes call Omni Intelligence/Agent-Reach style research tasks and output structured summaries/scripts.
• Every adapter must normalize progress, logs, artifacts, and errors into the orchestration event contract.

Progress and Logs

• The editor run panel shows total progress, active node, queued count, failed count, and latest logs.
• Each node visually reflects status and progress on the canvas.
• The scheduled task center shows run history with trigger, status, duration, completed nodes, failed node, artifacts, and retry/open actions.
• Logs should be structured with timestamp, level, nodeId, adapter, message, and optional artifact references.

Electron Isolation

• Keep orchestration control in the local runtime API.
• Use Electron UtilityProcess for heavy sidecars only when the desktop package is active.
• Isolate FFmpeg/FunClip/ASR/browser publishing from the renderer so crashes do not take down the workbench.
• Preserve the same endpoint/event contract in browser development and Electron packaged modes.

Data Contracts

Key TypeScript concepts:

• BusinessWorkflowDefinition
• BusinessWorkflowNode
• BusinessWorkflowEdge
• BusinessWorkflowSchedule
• BusinessWorkflowRun
• BusinessWorkflowNodeRun
• BusinessWorkflowEvent
• BusinessWorkflowArtifact
• BusinessWorkflowAdapter
• BusinessWorkflowValidationResult

The frontend and local runtime should share serializable contracts. Runtime-only fields such as process handles, secret values, and adapter clients must not appear in frontend payloads.

Migration Plan

1. Add OpenSpec and shared contracts.
2. Audit the existing /workflow implementation and convert the old stage presets into graph templates.
3. Replace the route body with the editor shell while preserving the current navigation and App Center entry.
4. Add React Flow node palette, drag/drop, edge creation, inspector editing, validation, and save/load.
5. Add the DAG engine with local mock adapters for deterministic tests.
6. Connect real adapters incrementally: intelligence/news, image, video, digital human, intelligent editing, publishing.
7. Add scheduled task center with Croner next-run preview and local runtime firing.
8. Add durable persistence and recovery, preferring SQLite in the desktop runtime.
9. Add Electron UtilityProcess isolation for heavy sidecars where needed.

Risks

• Long-running media generation and social publishing may exceed normal request lifetimes. Mitigation: run everything as durable local tasks with polling/SSE event streams.
• Platform publishing can fail due to account health or anti-automation. Mitigation: validate capabilities, preserve logs, and support retry per target.
• Node schemas can sprawl. Mitigation: keep node groups small, shared config sections reusable, and provider-specific options hidden until a provider is selected.
• Scheduling while the app is closed depends on the local runtime/desktop process being alive. Mitigation: surface scheduler health and missed-run policy clearly.