feat: Add workflow architecture and sequence diagram to documentation

- Introduced a new section for Workflow Architecture in README.md with a mermaid sequence diagram illustrating the standardized workflow logging pattern.
- Added a sequence diagram in AGENTS.md to visualize the workflow execution process, detailing interactions between User, BrowserApp, WorkflowProvider, AIBackend, WorkflowStep, and Writer.

Author: ssdeanx

README.md

@@ -134,6 +134,49 @@ graph TB
     style UI stroke:#58a6ff
 ```
 
+## 🔍 **Workflow Architecture**
+
+```mermaid
+%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#58a6ff', 'primaryTextColor': '#c9d1d9', 'primaryBorderColor': '#30363d', 'lineColor': '#58a6ff', 'sectionBkgColor': '#161b22', 'altSectionBkgColor': '#0d1117', 'sectionTextColor': '#c9d1d9', 'gridColor': '#30363d', 'tertiaryColor': '#161b22' }}}%%
+sequenceDiagram
+    participant W as Workflow Step
+    participant Writer as Writer (custom)
+    participant UI as UI/Frontend
+    
+    Note over W,UI: Standardized Workflow Logging Pattern
+    
+    W->>Writer: step-start event
+    Writer->>UI: data-workflow-step-start
+    Note right of UI: {type: "workflow", data: "step-id", id: "step-id"}
+    
+    W->>Writer: progress update (20%)
+    Writer->>UI: data-workflow-progress
+    Note right of UI: {status: "20%", message: "...", stage: "workflow"}
+    
+    W->>W: Execute step logic
+    
+    W->>Writer: progress update (50%)
+    Writer->>UI: data-workflow-progress
+    Note right of UI: {status: "50%", message: "...", stage: "workflow"}
+    
+    W->>W: Continue execution
+    
+    W->>Writer: progress update (100%)
+    Writer->>UI: data-workflow-progress
+    Note right of UI: {status: "100%", message: "...", stage: "workflow"}
+    
+    W->>Writer: step-complete event
+    Writer->>UI: data-workflow-step-complete
+    Note right of UI: {stepId: "step-id", success: true, duration: ms}
+    
+    Note over W,UI: Error Handling Pattern
+    
+    W->>W: Error occurs
+    W->>Writer: step-error event
+    Writer->>UI: data-workflow-step-error
+    Note right of UI: {stepId: "step-id", error: "error message"}
+```
+
 ## 📊 **System Flowchart**
 
 ```mermaid
@@ -989,56 +1032,117 @@ _Last updated: 2025-12-05 | v1.1.0_
 ```mermaid
 %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#58a6ff', 'primaryTextColor': '#c9d1d9', 'primaryBorderColor': '#30363d', 'lineColor': '#58a6ff', 'sectionBkgColor': '#161b22', 'altSectionBkgColor': '#0d1117', 'sectionTextColor': '#c9d1d9', 'gridColor': '#30363d', 'tertiaryColor': '#161b22' }}}%%
 classDiagram
-    class Message {
+    class WorkflowRun {
       +string id
-      +string role
-      +MessagePart[] parts
+      +string workflowId
+      +string status
+      +Date startedAt
+      +Date finishedAt
+      +string error
     }
 
-    class MessagePart {
-      +string type
-      +AgentDataPart data
+    class WorkflowDataPart {
+      +string messageId
+      +number partIndex
+      +DataPart part
     }
 
-    class AgentDataPart {
-      +string text
-      +string status
-      +string stage
-      +string stepId
-      +string message
-      +string agentId
-      +string workflowId
+    class DataPart {
+      +string type
+      +unknown data
     }
 
-    class ProgressEvent {
+    class WorkflowProgressEvent {
       +string id
       +string stage
       +string status
       +string message
-      +string agentId
-      +string workflowId
+      +string stepId
+      +Date timestamp
+      +unknown data
+    }
+
+    class WorkflowSuspendPayload {
+      +string message
+      +string requestId
+      +string stepId
     }
 
-    class NetworkProvider {
-      +ProgressEvent[] extractProgressEvents(messages)
+    class WorkflowContextValue {
+      +string selectedWorkflow
+      +WorkflowRun currentRun
+      +string status
+      +number activeStepIndex
+      +WorkflowProgressEvent[] progressEvents
+      +WorkflowSuspendPayload suspendPayload
+      +WorkflowDataPart[] dataParts
+      +selectWorkflow(workflowId)
+      +runWorkflow(inputData)
+      +pauseWorkflow()
+      +resumeWorkflow()
+      +stopWorkflow()
+      +runStep(stepId)
     }
 
     class WorkflowProvider {
-      +ProgressEvent[] extractProgressEvents(messages)
+      -WorkflowRun currentRun
+      -WorkflowProgressEvent[] progressEvents
+      -WorkflowDataPart[] dataParts
+      -WorkflowSuspendPayload suspendPayload
+      +useEffect_parseMessages()
+      +useEffect_syncStatus()
+      +runWorkflow(inputData)
+      +pauseWorkflow()
+      +resumeWorkflow()
+      +stopWorkflow()
+      +runStep(stepId)
     }
 
-    class ProgressPanel {
-      +void render(progressEvents)
+    class WriterCustomPayload {
+      +string type
+      +unknown data
+      +string id
     }
 
-    Message "1" --> "*" MessagePart : has
-    MessagePart "1" --> "0..1" AgentDataPart : data
+    class Writer {
+      +custom(payload)
+    }
+
+    class StepExecutionContext {
+      +unknown inputData
+      +Writer writer
+      +unknown mastra
+    }
+
+    class WorkflowStep {
+      +string id
+      +execute(context)
+    }
+
+    class UpstashVector {
+      +createIndex(indexName, dimension, metric)
+    }
+
+    class UpstashConfig {
+      +initializeUpstashVector()
+      +UpstashVector upstashVector
+    }
+
+    WorkflowProvider ..> WorkflowContextValue : provides
+    WorkflowProvider --> WorkflowRun : manages
+    WorkflowProvider --> WorkflowProgressEvent : aggregates
+    WorkflowProvider --> WorkflowDataPart : collects
+    WorkflowProvider --> WorkflowSuspendPayload : handles
+
+    WorkflowContextValue o--> WorkflowRun
+    WorkflowContextValue o--> WorkflowProgressEvent
+    WorkflowContextValue o--> WorkflowDataPart
+    WorkflowContextValue o--> WorkflowSuspendPayload
 
-    NetworkProvider --> Message : reads
-    WorkflowProvider --> Message : reads
+    WorkflowStep --> StepExecutionContext : uses
+    StepExecutionContext o--> Writer
 
-    NetworkProvider --> ProgressEvent : creates_with_id_messageId_partType_partIndex
-    WorkflowProvider --> ProgressEvent : creates_with_id_messageId_partType_partIndex
+    Writer --> WriterCustomPayload : sends
 
-    ProgressPanel "1" --> "*" ProgressEvent : renders
+    UpstashConfig o--> UpstashVector
 ```

src/mastra/workflows/AGENTS.md

@@ -180,6 +180,63 @@ execute: async ({ inputData, writer }) => {
 }
 ```
 
+# Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant BrowserApp
+    participant WorkflowProvider
+    participant AIBackend
+    participant WorkflowStep
+    participant Writer
+
+    User->>BrowserApp: Click run workflow
+    BrowserApp->>WorkflowProvider: runWorkflow(inputData)
+    WorkflowProvider->>AIBackend: send workflow start message
+
+    AIBackend->>WorkflowStep: execute({ inputData, writer })
+    activate WorkflowStep
+
+    note over WorkflowStep: Step start
+    WorkflowStep->>Writer: custom(type: data-workflow-step-start, id: stepId)
+    Writer-->>AIBackend: stream message part (data-workflow-step-start)
+    AIBackend-->>WorkflowProvider: assistant message with data-workflow-step-start
+    WorkflowProvider->>WorkflowProvider: extract dataParts
+
+    note over WorkflowStep: Progress updates
+    WorkflowStep->>Writer: custom(type: data-workflow-progress, status: 20%)
+    Writer-->>AIBackend: stream progress part
+    AIBackend-->>WorkflowProvider: assistant message with data-workflow-progress
+    WorkflowProvider->>WorkflowProvider: add WorkflowProgressEvent
+
+    WorkflowStep->>WorkflowStep: perform main logic
+
+    alt success
+        WorkflowStep->>Writer: custom(type: data-workflow-progress, status: 100%)
+        Writer-->>AIBackend: final progress part
+        AIBackend-->>WorkflowProvider: assistant message with data-workflow-progress
+        WorkflowProvider->>WorkflowProvider: update progressEvents
+
+        WorkflowStep->>Writer: custom(type: data-workflow-step-complete, success: true)
+        Writer-->>AIBackend: step complete part
+        AIBackend-->>WorkflowProvider: assistant message with data-workflow-step-complete
+        WorkflowProvider->>WorkflowProvider: update activeStepIndex
+    else error
+        WorkflowStep->>Writer: custom(type: data-workflow-step-error, error)
+        Writer-->>AIBackend: step error part
+        AIBackend-->>WorkflowProvider: assistant message with data-workflow-step-error
+        WorkflowProvider->>WorkflowProvider: add error progressEvent
+    end
+
+    WorkflowStep-->>AIBackend: return result or throw
+    deactivate WorkflowStep
+
+    AIBackend-->>WorkflowProvider: final completion message
+    WorkflowProvider-->>BrowserApp: updated context (progressEvents, dataParts)
+    BrowserApp-->>User: render workflow progress UI
+```
+
 ---
 ## Change Log