Technical Documentation: State Machine Logic

Architecture

The State Machine system consists of a visual node-based Editor (Frontend) and an asynchronous execution engine (Go Backend). It manages complex directed graphs.

Technical Details

• File Paths:
  • lib/screens/state_machine_screen.dart (Dashboard & History)
  • lib/screens/state_machine_editor_screen.dart (Visual Builder)
• State Store: StateMachineFlow model (nodes, connections, and metadata).
• Communication: Uses REST for CRUD and WebSocket/Socket.IO for live execution feedback.

Graph Logic

• Nodes: Represent discrete task states. They store configuration parameters localized to that specific step.
• Connections (Edges): Define the transition logic. Connections are tied to "Outcomes" (e.g., "On Success" → move to Node B; "On Failure" → move to Error Handler).
• Execution Loop:
  • The engine keeps a "Current Pointer" to the active Node ID.
  • Upon completion of the task, it looks up the connection matching the Outcome.
  • Transitions to next ID and repeats until the "End Node" is reached.

Live Feedback System

• Status Polling: The UI polls the backend every 1.5s for the current execution state.
• Node Highlighting: The editor uses state data to visually update node borders and icons (e.g., green pulse for "Running", checkmark for "Finished").
• Validation: Ensures a flow has exactly one "Start" node and reachable "End" nodes before allowing a save.

Execution History

Stores detailed per-step metrics:

• start_time, end_time
• status (success/failed/canceled)
• message (raw logs from the task executor)