Story (Process Flow)

Note: This documentation describes the current story-based architecture. Stories are first-class database entities that represent process flows.

A Story represents a flow of work through a process, documenting how actors, features, and data objects interact to accomplish a goal.

Key Concepts

Stories are:

• First-class entities: Stored as independent documents in the database
• Ordered sequences: Each story has an order field for sequencing
• Narrative-based: Describe "who does what with what data"
• Visually rendered as edges: Appear as arrows in process diagrams

Story Structure

Each story contains:

• Source Element: Who initiates the action (actor, feature, timer, process)
• Target Element: Who receives or processes (actor, feature, process)
• Data Object (optional): What data is involved
• Label: Action verb describing the flow (e.g., "submits", "validates")
• Condition (optional): Business logic (e.g., "if approved")
• Order: Sequence number for story ordering

How It Works

Stories are rendered as edges (arrows) in the process diagram, with the edge type set to 'process_step' for visual styling.

Story Labels

Good story labels are action-oriented:

• "submits order"
• "validates payment"
• "creates invoice"
• "sends confirmation"

Conditions

Use conditions to document decision points:

• "if credit check passes"
• "when stock is available"
• "for international orders"

Conditions create a diamond node in the diagram to show branching logic.

Process Orchestration

Stories can orchestrate multiple processes:

Triggers (starts another process):

• Set triggersProcessId field on the story
• Creates an orange solid arrow at landscape level
• Shows this process kicks off another process

Awaits (waits for completion):

• Set awaitsProcessId field on the story
• Creates a green dashed arrow at landscape level
• Shows this process depends on another finishing

Data Architecture

Stories are stored as:

{
  "_id": "story-uuid-123",
  "elementType": "story",
  "processId": "proc-456",
  "sourceElementId": "actor-1",
  "targetElementId": "feature-2",
  "dataObjectId": "data-3",  // optional
  "label": "submits order",
  "condition": "if approved",  // optional
  "order": 10,
  "triggersProcessId": null,  // optional
  "awaitsProcessId": null     // optional
}

Story Editor

Stories are managed through the Story Editor modal:

• View all stories for a process
• Reorder stories with drag-and-drop
• Edit story details
• See narrative visualization

Integration

• Storage: First-class database entities with elementType: 'story'
• Rendering: Edges with type: 'process_step' in Cytoscape graph
• Ordering: order field determines sequence
• CRUD: Use EntityService methods: createStory(), updateStory(), deleteStory()

Tips

• Use clear, action-oriented labels
• Sequence stories logically using the order field
• Document conditions for clarity
• Use orchestration for complex workflows
• Manage stories through the Story Editor modal

Migration from Old Architecture

Historical Note: Previously, process steps were stored as embedded arrays in process documents. The current architecture uses first-class story entities for better flexibility and querying.