Skip to content

Commit 293152b

Browse files
sfmskywalkersfmskywalker
committed
Adds documentation for Devin
Creates a comprehensive documentation structure for the Elsa Workflows project. This includes an overview of the system, getting started guide, key concepts, solution structure, core execution engine, activity system, variable/memory management, and expression evaluation.
1 parent 103063e commit 293152b

1 file changed

Lines changed: 303 additions & 0 deletions

File tree

‎.devin/wiki.json‎

Lines changed: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
{
2+
"repo_notes": [
3+
{
4+
"content": "Elsa 3 is a .NET workflow library that lets you build workflows in C#, with a visual designer, or in JSON; the repo also ships reference server and studio apps and Docker images for quick starts."
5+
}
6+
],
7+
"pages": [
8+
{
9+
"title": "Introduction to Elsa Workflows",
10+
"purpose": "Introduce the Elsa Workflows system, its purpose as a .NET workflow engine, and high-level architecture overview",
11+
"page_notes": [
12+
{
13+
"content": "Elsa enables running workflows inside any .NET app with definitions authored in C#, visually, or as JSON, pairing a workflow engine with a web-based designer and server/studio reference apps."
14+
}
15+
]
16+
},
17+
{
18+
"title": "Getting Started",
19+
"purpose": "Guide users through installation, Docker quick start, and running their first workflow",
20+
"parent": "Introduction to Elsa Workflows",
21+
"page_notes": [
22+
{
23+
"content": "Use the published Docker image `elsaworkflows/elsa-server-and-studio-v3:latest` to run the reference server+designer, exposing port 8080 on container to localhost:13000 with admin/password login; images include CA bundles with optional EXTRA_CA_CERT/SSL_CERT_FILE support for custom trust."
24+
}
25+
]
26+
},
27+
{
28+
"title": "Key Concepts",
29+
"purpose": "Explain fundamental concepts: workflows, activities, bookmarks, execution contexts, and state management",
30+
"parent": "Introduction to Elsa Workflows",
31+
"page_notes": [
32+
{
33+
"content": "Workflows are graphs of activities; execution contexts (workflow and activity) hold runtime data like variables and memory registers, schedule work, and capture bookmarks for resumption and persistence."
34+
}
35+
]
36+
},
37+
{
38+
"title": "Solution Structure",
39+
"purpose": "Document the project organization, module hierarchy, and how the solution is structured",
40+
"parent": "Introduction to Elsa Workflows",
41+
"page_notes": [
42+
{
43+
"content": "Opening Elsa.sln exposes an apps folder with reference hosts: Elsa.Server.Web (workflow server), Elsa.ServerAndStudio.Web (server plus Blazor Studio), and Elsa.Studio.Web (standalone Studio needing a server)."
44+
}
45+
]
46+
},
47+
{
48+
"title": "Core Execution Engine",
49+
"purpose": "Deep dive into the workflow execution engine architecture, contexts, and execution pipeline",
50+
"page_notes": [
51+
{
52+
"content": "WorkflowRunner builds workflow graphs, creates WorkflowExecutionContext instances with identity, correlation, input, and schedules the root workflow before handing execution to the pipeline."
53+
}
54+
]
55+
},
56+
{
57+
"title": "Workflow Execution Context",
58+
"purpose": "Explain WorkflowExecutionContext: its role, properties, memory register, scheduler, and lifecycle",
59+
"parent": "Core Execution Engine",
60+
"page_notes": [
61+
{
62+
"content": "WorkflowExecutionContext initializes scheduler, memory register, input/properties, incidents, bookmarks, cancellation handling, and exposes creation helpers that hydrate state and wire ExpressionExecutionContext."
63+
}
64+
]
65+
},
66+
{
67+
"title": "Activity Execution Context",
68+
"purpose": "Explain ActivityExecutionContext: parent-child relationships, variable scoping, and activity state management",
69+
"parent": "Core Execution Engine",
70+
"page_notes": [
71+
{
72+
"content": "ActivityExecutionContext tracks activity instance IDs, parent-child links, execution status, timestamps, dynamic variables, and constructs an ExpressionExecutionContext chain to scope variables and expressions."
73+
}
74+
]
75+
},
76+
{
77+
"title": "Workflow Runner and Pipeline",
78+
"purpose": "Document WorkflowRunner orchestration, execution pipeline middleware, and activity invoker",
79+
"parent": "Core Execution Engine",
80+
"page_notes": [
81+
{
82+
"content": "WorkflowRunner orchestrates execution by scheduling workflows or bookmarks on a WorkflowExecutionContext then invoking the configured IWorkflowExecutionPipeline, also supporting restoration from WorkflowState and variable injection."
83+
}
84+
]
85+
},
86+
{
87+
"title": "State Persistence and Restoration",
88+
"purpose": "Explain WorkflowStateExtractor, WorkflowState serialization, and state hydration mechanisms",
89+
"parent": "Core Execution Engine",
90+
"page_notes": [
91+
{
92+
"content": "WorkflowStateExtractor serializes workflow instance fields (IDs, status, bookmarks, input/output, incidents, scheduled work, completion callbacks, activity contexts) and can rehydrate a WorkflowExecutionContext by reconstructing activities, properties, variables, and schedules."
93+
}
94+
]
95+
},
96+
{
97+
"title": "Activity Scheduling and Work Items",
98+
"purpose": "Document the activity scheduler, work item queue, and how activities are scheduled for execution",
99+
"parent": "Core Execution Engine",
100+
"page_notes": [
101+
{
102+
"content": "The default QueueBasedActivityScheduler is a FIFO queue of ActivityWorkItem entries, supporting enqueue/dequeue, lookup, and clear operations to drive the workflow dispatcher."
103+
}
104+
]
105+
},
106+
{
107+
"title": "Bookmarks and Resumption",
108+
"purpose": "Explain the bookmark system for pausing and resuming workflows, including bookmark queue processing",
109+
"page_notes": [
110+
{
111+
"content": "Bookmarks capture pause points with IDs, names, and hashes that can be persisted and resumed; runtime models like NewBookmarkQueueItem carry bookmark IDs, hashes, correlation, and resume options for async resumption."
112+
}
113+
]
114+
},
115+
{
116+
"title": "Bookmark System",
117+
"purpose": "Detail bookmark creation, hashing, storage, and how workflows suspend/resume at bookmarks",
118+
"parent": "Bookmarks and Resumption",
119+
"page_notes": [
120+
{
121+
"content": "BookmarkInfo stores bookmark ID, name, and computed hash, enabling lookup and comparison when resuming workflows from persisted bookmark payloads."
122+
}
123+
]
124+
},
125+
{
126+
"title": "Trigger System",
127+
"purpose": "Explain workflow triggers, trigger stores, and how external events initiate workflow execution",
128+
"parent": "Bookmarks and Resumption",
129+
"page_notes": [
130+
{
131+
"content": "Triggers bind external stimuli to workflow bookmarks via runtime metadata (stimulus hashes, activity types, correlation IDs), enabling workflows to start or resume when matching events arrive."
132+
}
133+
]
134+
},
135+
{
136+
"title": "Bookmark Queue",
137+
"purpose": "Document bookmark queue processing, purging, and asynchronous workflow resumption",
138+
"parent": "Bookmarks and Resumption",
139+
"page_notes": [
140+
{
141+
"content": "NewBookmarkQueueItem entries encapsulate workflow instance IDs, bookmark IDs or stimulus hashes, activity instance references, correlation IDs, and resume options for queue-driven resumption."
142+
}
143+
]
144+
},
145+
{
146+
"title": "Activity System",
147+
"purpose": "Overview of the activity system: IActivity interface, activity types, and execution patterns",
148+
"page_notes": [
149+
{
150+
"content": "Activities encapsulate executable steps; WorkflowRunner can start from an activity by building a workflow graph, while activity descriptors surface outputs and metadata used during execution and composition."
151+
}
152+
]
153+
},
154+
{
155+
"title": "Control Flow Activities",
156+
"purpose": "Document branching and looping: If, Switch, Sequence, Flowchart, FlowJoin, Break, Complete",
157+
"parent": "Activity System",
158+
"page_notes": [
159+
{
160+
"content": "Flowchart is a primary control-flow container with start nodes and connections; it can operate in counter-based or token-based modes configured via FlowchartOptions or execution context properties."
161+
}
162+
]
163+
},
164+
{
165+
"title": "HTTP Activities",
166+
"purpose": "Detail HttpEndpoint and SendHttpRequest activities, including configuration and usage patterns",
167+
"parent": "Activity System",
168+
"page_notes": [
169+
{
170+
"content": "The README’s coding example shows HttpEndpoint starting a workflow and subsequent activities (like SendEmail) handling the request, illustrating HTTP-triggered workflows."
171+
}
172+
]
173+
},
174+
{
175+
"title": "Workflow Composition Activities",
176+
"purpose": "Explain Composite, WorkflowDefinitionActivity, and how workflows can invoke other workflows",
177+
"parent": "Activity System",
178+
"page_notes": [
179+
{
180+
"content": "Workflow activities create memory registers, declare result variables, and can schedule child activities, supporting hierarchical composition of workflows."
181+
}
182+
]
183+
},
184+
{
185+
"title": "Activity Outputs and Registry",
186+
"purpose": "Document ActivityOutputRegister, output resolution, and how activities expose results",
187+
"parent": "Activity System",
188+
"page_notes": [
189+
{
190+
"content": "ActivityOutputRegister records outputs by activity ID and instance, normalizing output names via descriptors and enabling lookup of latest values scoped to parent contexts."
191+
}
192+
]
193+
},
194+
{
195+
"title": "Activity Descriptors and Metadata",
196+
"purpose": "Explain ActivityDescriptor, how activities are described, and the activity provider system",
197+
"parent": "Activity System",
198+
"page_notes": [
199+
{
200+
"content": "Activity descriptors describe inputs/outputs; registration is resolved via IActivityRegistry and lookup services injected into WorkflowExecutionContext for descriptor-aware execution."
201+
}
202+
]
203+
},
204+
{
205+
"title": "Flowchart Execution Modes",
206+
"purpose": "Detail TokenBased vs CounterBased execution modes, FlowScope, and flowchart-specific behavior",
207+
"parent": "Activity System",
208+
"page_notes": [
209+
{
210+
"content": "Flowchart exposes a static UseTokenFlow toggle and stores execution mode in workflow properties; scheduling callbacks delegate to token-based or counter-based handlers for completion and cancellation logic."
211+
}
212+
]
213+
},
214+
{
215+
"title": "Variable and Memory System",
216+
"purpose": "Overview of variable management, memory registers, and variable persistence",
217+
"page_notes": [
218+
{
219+
"content": "Workflows create MemoryRegister instances that hold declared variables; variables reference memory blocks with optional storage drivers for persistence across executions."
220+
}
221+
]
222+
},
223+
{
224+
"title": "Variable Management",
225+
"purpose": "Document Variable class, variable scoping, IVariableContainer, and dynamic variables",
226+
"parent": "Variable and Memory System",
227+
"page_notes": [
228+
{
229+
"content": "Variable types derive from MemoryBlockReference, carrying names, default values, storage driver types, and helper methods to bind IDs or values; ActivityExecutionContext merges container and dynamic variables for scope."
230+
}
231+
]
232+
},
233+
{
234+
"title": "Type Conversion",
235+
"purpose": "Explain ObjectConverter, type conversion strategies, and handling complex type transformations",
236+
"parent": "Variable and Memory System",
237+
"page_notes": [
238+
{
239+
"content": "ExpressionExecutionContext converts variable values when retrieved, enabling typed accessors like Variable<T>.Get that rely on conversion helpers for strongly typed results."
240+
}
241+
]
242+
},
243+
{
244+
"title": "Variable Persistence",
245+
"purpose": "Document IVariablePersistenceManager, storage drivers, and how variables are saved/loaded",
246+
"parent": "Variable and Memory System",
247+
"page_notes": [
248+
{
249+
"content": "VariablePersistenceManager ensures memory blocks exist for variables and leverages storage drivers (e.g., WorkflowStorageDriver) when persisting workflow state during extraction and hydration."
250+
}
251+
]
252+
},
253+
{
254+
"title": "Memory Register and Memory Blocks",
255+
"purpose": "Explain MemoryRegister, MemoryBlock, MemoryBlockReference, and how memory is managed",
256+
"parent": "Variable and Memory System",
257+
"page_notes": [
258+
{
259+
"content": "Workflow activities call CreateRegister to allocate a MemoryRegister that stores MemoryBlock references declared by variables and supports scoped memory across workflow execution contexts."
260+
}
261+
]
262+
},
263+
{
264+
"title": "Expression Evaluation",
265+
"purpose": "Overview of the expression system, ExpressionExecutionContext, and supported languages",
266+
"page_notes": [
267+
{
268+
"content": "ExpressionExecutionContext is created for workflows and chained for activities, carrying memory registers and properties so expressions can resolve variables and activity data across supported languages."
269+
}
270+
]
271+
},
272+
{
273+
"title": "Expression Execution Context",
274+
"purpose": "Detail ExpressionExecutionContext, parent chains, and how expressions access workflow data",
275+
"parent": "Expression Evaluation",
276+
"page_notes": [
277+
{
278+
"content": "ActivityExecutionContext builds an ExpressionExecutionContext with the workflow’s input and parent chain, inserting the current activity in context properties for expression access."
279+
}
280+
]
281+
},
282+
{
283+
"title": "C# Expressions",
284+
"purpose": "Document C# expression evaluation using Roslyn and available APIs",
285+
"parent": "Expression Evaluation",
286+
"page_notes": [
287+
{
288+
"content": "C# expression support plugs into the common ExpressionExecutionContext, benefiting from the same variable/memory access patterns used across languages."
289+
}
290+
]
291+
},
292+
{
293+
"title": "JavaScript Expressions",
294+
"purpose": "Explain Jint-based JavaScript evaluation, type definitions, and activity output access",
295+
"parent": "Expression Evaluation",
296+
"page_notes": [
297+
{
298+
"content": "JavaScript expressions execute through the shared expression context, enabling access to workflow input, activity outputs, and variables resolved from memory registers."
299+
}
300+
]
301+
}
302+
]
303+
}

0 commit comments

Comments
 (0)