docs: Add business overview with validated technical details #331
Conversation
Reviewer's GuideAdds a new business-facing overview document for the vNext Workflow Engine that explains platform capabilities, core features, integration, and operational aspects, all tied explicitly to underlying .NET implementation details and architectural components. Sequence diagram for auto transition chaining with RequiresNew unit of worksequenceDiagram
participant API as OrchestrationAPI
participant Engine as ExecutionHost
participant Ctx as WorkflowExecutionContext
participant Runner as ITransitionRunner
participant Script as IScriptEngine
participant AutoEval as IAutoConditionEvaluator
participant Pipe as PipelineDirectives
participant UoW as UnitOfWorkRequiresNew
API->>Engine: TriggerTransition(instanceId, transitionId)
Engine->>Ctx: CreateExecutionContext(domain, instanceId, workflowId)
Engine->>Runner: Run(Ctx, initialTransition)
loop EvaluateAutoTransition
Runner->>Script: CreateScriptContext(instance, workflow, headers, taskResponse)
Script-->>Runner: ScriptContext
Runner->>AutoEval: Evaluate(Transition.Rule, ScriptContext)
AutoEval-->>Runner: ConditionResult
alt ConditionResult is Satisfied
Runner->>Pipe: Set NextTransition
Runner-->>Engine: Completed with NextTransition
Engine->>UoW: BeginScopeRequiresNew(domain, instanceId)
UoW->>Runner: Run(Ctx, Pipe.NextTransition)
UoW-->>Engine: Commit
else No further auto transition
Runner-->>Engine: Completed without NextTransition
end
end
Engine-->>API: TransitionPipelineResult
Class diagram for core workflow definition and execution typesclassDiagram
class Workflow {
+Guid Id
+string Name
+List~State~ States
+List~Transition~ SharedTransitions
+Transition FindTransitionInContext(Guid stateId, Guid transitionId)
}
class State {
+Guid Id
+string Name
+List~Transition~ Transitions
+SubFlow SubFlow
+Transition DefaultAutoTransition
}
class Transition {
+Guid Id
+string Name
+TriggerType TriggerType
+string Rule
+List~string~ AvailableIn
}
class SubFlow {
+Guid WorkflowId
+bool IsBlocking
+string ScriptCodeInput
+string ScriptCodeOutput
}
class WorkflowExecutionContext {
+string Domain
+Guid InstanceId
+Guid WorkflowId
}
class RuntimeOptions {
+List~RuntimeSysSchemaInfo~ SystemSchemas
}
class RuntimeSysSchemaInfo {
+string SchemaName
+string DbContextType
}
class SyncSchemaValidator {
+Validate(RuntimeOptions options)
}
class IScriptEngine {
+Compile(string code)
+Execute(ScriptContext context)
}
class ScriptContext {
+object Instance
+Workflow Workflow
+Dictionary~string,string~ Headers
+object TaskResponse
}
class ScriptContextFactory {
+Create(object instance, Workflow workflow, Dictionary~string,string~ headers, object taskResponse)
}
class IAutoConditionEvaluator {
+ConditionResult Evaluate(string rule, ScriptContext context)
}
class ITransitionRunner {
+Run(WorkflowExecutionContext context, Transition transition)
}
class PipelineDirectives {
+Transition NextTransition
+bool HasNext
}
class IDomainDiscoveryResolver {
+ServiceEndpoint Resolve(string domain)
}
class DomainRegistrationService {
+Register(string domain, ServiceEndpoint endpoint)
}
class DaprServiceTaskInvoker {
+Invoke(ServiceEndpoint endpoint, object payload)
}
class DaprBindingTaskInvoker {
+InvokeBinding(string bindingName, object payload)
}
Workflow "1" --> "*" State
Workflow "1" --> "*" Transition : SharedTransitions
State "1" --> "*" Transition
State "0..1" --> "1" SubFlow
SubFlow "1" --> "1" Workflow : ChildWorkflow
WorkflowExecutionContext "1" --> "1" Workflow
RuntimeOptions "1" --> "*" RuntimeSysSchemaInfo
SyncSchemaValidator --> RuntimeOptions
ScriptContextFactory --> ScriptContext
ScriptContext "1" --> "1" Workflow
IScriptEngine --> ScriptContext
IAutoConditionEvaluator --> ScriptContext
ITransitionRunner --> WorkflowExecutionContext
ITransitionRunner --> Transition
ITransitionRunner --> PipelineDirectives
IDomainDiscoveryResolver --> DomainRegistrationService
DaprServiceTaskInvoker --> IDomainDiscoveryResolver
DaprBindingTaskInvoker --> IDomainDiscoveryResolver
Flow diagram for hierarchical SubFlow executionflowchart LR
Start([Parent workflow state enters])
CheckSubFlow{State has SubFlow?}
NoSubFlow[Execute state tasks and wait for trigger]
Configure[Configure SubFlow execution type]
Blocking{IsBlocking SubFlow?}
StartChild[Start child workflow instance]
ParentWait[Parent waits for child completion]
ParentContinue[Parent continues without waiting]
ChildRunning[[Child workflow executes]]
ChildComplete{Child completes or fails}
MapOutput[Map child output via ScriptCodeOutput]
UpdateParent[Update parent instance data]
ResumeParent[Resume parent workflow and evaluate next transitions]
Start --> CheckSubFlow
CheckSubFlow -- No --> NoSubFlow
CheckSubFlow -- Yes --> Configure
Configure --> Blocking
Blocking -- Yes --> StartChild
StartChild --> ParentWait
ParentWait --> ChildRunning
ChildRunning --> ChildComplete
ChildComplete --> MapOutput
MapOutput --> UpdateParent
UpdateParent --> ResumeParent
Blocking -- No --> StartChild
StartChild --> ParentContinue
ParentContinue --> ResumeParent
NoSubFlow --> ResumeParent
ResumeParent --> End([State finished])
File-Level Changes
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Summary of ChangesHello @khizer-flow, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces the foundational business overview documentation for the vNext Workflow Engine. It provides a comprehensive, technically validated description of the engine's platform capabilities, core features, integration points, and operational aspects, aiming to bridge the gap between business requirements and technical implementation. The document serves as an initial draft, with specific sections marked for future collaborative refinement. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
Note
|
| Cohort / File(s) | Summary |
|---|---|
Business Documentation docs/business/overview.md |
New file documenting vNext Workflow Engine business context, architecture patterns, platform capabilities (JSON-first definitions, Builder API, graph resolution), features (dynamic C# scripting, auto transitions, service discovery), integration points (REST, Dapr), and operational concerns (OpenTelemetry, health endpoints) |
Estimated code review effort
🎯 1 (Trivial) | ⏱️ ~5 minutes
Possibly related issues
- Issue
#330: Directly addresses the addition of business-focused vNext Workflow Engine documentation covering architecture and platform capabilities as requested.
Suggested reviewers
- tsimsekburgan
Poem
🐰 A business tale, so crisp and bright,
Of workflows dancing day and night,
With Roslyn's spark and Dapr's grace,
We've mapped this grand engine's place!
Documentation hops along with glee,
The vNext vision, for all to see ✨
🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
| Check name | Status | Explanation |
|---|---|---|
| Description Check | ✅ Passed | Check skipped - CodeRabbit’s high-level summary is enabled. |
| Title check | ✅ Passed | The title accurately summarizes the main change: adding a new business overview documentation file with validated technical details, which matches the PR objective of introducing initial business documentation with technical validation. |
| Docstring Coverage | ✅ Passed | No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. |
✏️ Tip: You can configure your own custom pre-merge checks in the settings.
✨ Finishing touches
🧪 Generate unit tests (beta)
- Create PR with unit tests
- Post copyable unit tests in a comment
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment @coderabbitai help to get the list of available commands and usage tips.
|
Here's the code health analysis summary for commits Analysis Summary
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- Some of the stronger guarantees (“guarantee data integrity and isolation”, “preventing cross-tenant data leakage at the API boundary”) might be better framed more precisely (e.g., describing the mechanisms and typical failure modes) to avoid over-promising behavior that still depends on correct usage and deployment.
- Where you reference specific types/members (e.g.,
Workflow.Create(),FindTransitionInContext,IAutoConditionEvaluator,DomainRegistrationService), consider aligning the terminology with actual current signatures and namespaces or qualifying when names are illustrative, so the doc doesn’t become misleading if the code evolves.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- Some of the stronger guarantees (“guarantee data integrity and isolation”, “preventing cross-tenant data leakage at the API boundary”) might be better framed more precisely (e.g., describing the mechanisms and typical failure modes) to avoid over-promising behavior that still depends on correct usage and deployment.
- Where you reference specific types/members (e.g., `Workflow.Create()`, `FindTransitionInContext`, `IAutoConditionEvaluator`, `DomainRegistrationService`), consider aligning the terminology with actual current signatures and namespaces or qualifying when names are illustrative, so the doc doesn’t become misleading if the code evolves.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive business overview document for the vNext Workflow Engine, effectively detailing its architecture, capabilities, and core features. The document successfully integrates validated technical details, mapping business functionalities to their underlying code implementations, which aligns well with the stated objectives of the PR. The structure is clear, and the content is informative for the target audience. The document provides a good balance between high-level business value propositions and specific technical insights, such as multi-tenancy, scripting, and auto-transitions.
1 participant
This PR adds the initial draft for the Business Documentation as discussed in issue #330.
Changes:
Drafted Sections 2 (Platform Capabilities) & 3 (Core Features): Conducted a deep-dive analysis of BBT.Workflow.Domain and BBT.Workflow.Execution to map business features to actual code implementations.
Technical Validation: Verified key architectural claims against the source code, including:
Multi-tenancy: Confirmed schema isolation via RuntimeOptions and SyncSchemaValidator.
Scripting: Confirmed Roslyn-based dynamic execution via IScriptEngine.
Reliability: Documented the Aether Inbox/Outbox pattern implementation in Infrastructure.
Auto-transitions: Clarified the RequiresNew transaction scope logic for chained transitions.
Executive Summary: Included a placeholder draft for Section 1, ready for collaboration to align with specific business value propositions.
Next Steps:
Review of the technical accuracy in Sections 2-5.
Collaborative refinement of the Executive Summary (Section 1) to finalize the business messaging.
Summary by Sourcery
Add a business-focused overview document for the vNext Workflow Engine describing its architecture, capabilities, and core features.
Documentation:
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.