elsa-core/doc/wiki

Elsa Core Wiki

This wiki is a repo-local, code-grounded map of Elsa Core. It is intended for contributors who need the same kind of fast orientation that a DeepWiki-style generated wiki gives: what the system is, where the important code lives, how the pieces connect, and how to safely extend or test them.

The source of truth is still the code, specs, ADRs, and tests. Each page links back to the relevant files so you can jump from explanation to implementation.

Start Here

Elsa Core is a modular .NET workflow engine. The main solution is Elsa.sln. Production code lives under src, tests under test, specifications under specs, and architecture decisions under doc/adr.

The shortest mental model:

1. An application calls services.AddElsa(...).
2. Elsa builds an IModule and configures feature objects.
3. Features register services, activities, API endpoints, middleware, hosted services, and persistence stores.
4. Workflow definitions are created by code, JSON, imported files, or providers.
5. The runtime starts, resumes, dispatches, and persists workflow instances.
6. APIs, SignalR hubs, HTTP endpoint activities, diagnostics, and persistence packages layer around that core.

flowchart LR
    App["Host app"] --> Module["Elsa module system"]
    Module --> Core["Workflow core"]
    Module --> Management["Workflow management"]
    Module --> Runtime["Workflow runtime"]
    Module --> Api["Workflow API"]
    Module --> Extensions["HTTP, Scheduling, Expressions, Identity, Tenants"]
    Management --> Persistence["Stores / EF Core providers"]
    Runtime --> Persistence
    Runtime --> Logs["Execution logs and diagnostics"]
    Api --> Studio["Elsa Studio / API clients"]

Page Map

Page	Use it for
Repository Map	Top-level folders, projects, and where to look first.
Architecture	The main system layers and request/execution flow.
Module System	How IModule, FeatureBase, feature dependencies, and shell features work.
Workflow Core	Activities, execution contexts, pipelines, variables, bookmarks, graphs, and flowchart execution.
Workflow Management	Workflow definitions, instances, import/export, materializers, validation, and activity descriptors.
Workflow Runtime	Dispatch, triggers, bookmarks, queues, background activity scheduling, graceful shutdown, and recovery.
Workflow API	FastEndpoints, route prefixing, API categories, SignalR, and client-facing contracts.
Activities And Authoring	How workflows are authored in C#, JSON, ElsaScript, and host methods.
Output Converters	How to register, configure, validate, discover, and operate bound-value converters.
Expressions And Scripting	Expression evaluators and language feature packages.
HTTP, Scheduling, And Resilience	Inbound HTTP workflows, outbound HTTP, scheduled triggers, and resilience strategies.
Persistence	In-memory stores, EF Core stores, provider packages, migrations, and multi-provider rules.
Diagnostics Structured Logs	ILogger capture, live feed, REST/SignalR surface, redaction, and SQLite persistence.
Diagnostics Console Logs	Raw stdout/stderr capture, live feed, REST/SignalR surface, and redaction.
Health Checks	Elsa runtime readiness probes, liveness/readiness mapping, and Kubernetes probe guidance.
Identity, Tenancy, And Security	Users, applications, roles, API keys, tenant resolution, and authorization touch points.
Testing Guide	Test project layout, fixture choices, and targeted commands.
Extension Guide	How to add features, activities, expression providers, stores, endpoints, and ingress sources.
OpenTelemetry Workflow Instrumentation	First-party workflow and activity traces and metrics emitted through System.Diagnostics.
Specs And ADRs	How current specs and ADRs explain design intent.
Build, Run, And Operate	Build commands, sample hosts, runtime knobs, Docker notes, and operational endpoints.

Source Landmarks

• Main public entry: src/modules/Elsa/Extensions/DependencyInjectionExtensions.cs
• Default umbrella feature: src/modules/Elsa/Features/ElsaFeature.cs
• Module implementation: src/common/Elsa.Features/Implementations/Module.cs
• Core workflow feature: src/modules/Elsa.Workflows.Core/Features/WorkflowsFeature.cs
• Management feature: src/modules/Elsa.Workflows.Management/Features/WorkflowManagementFeature.cs
• Runtime feature: src/modules/Elsa.Workflows.Runtime/Features/WorkflowRuntimeFeature.cs
• API feature: src/modules/Elsa.Workflows.Api/Features/WorkflowsApiFeature.cs
• Reference server: src/apps/Elsa.Server.Web/Program.cs
• Structured-log persistence design: specs/005-structured-log-persistence/plan.md

Contributor Workflow

Use targeted reads first, then targeted tests. For most changes, start with the relevant module page, inspect the linked feature class and contracts, add or update tests in the matching test/unit, test/integration, or test/component project, and run the narrowest dotnet test command that proves the behavior.

When changing public behavior, update the related README, spec quickstart, or wiki page in the same PR. This repository is strongly modular, so the best changes keep ownership boundaries clear.