elsa-core/doc/wiki/repository-map.md

Repository Map

Elsa Core is organized as a large multi-project .NET solution. The repo favors small, independently packaged modules over one monolith.

Top-Level Layout

Path	Purpose
src/apps	Runnable reference hosts, load-balancer host, modular server host, and sample package.
src/modules	Elsa product modules: workflow engine, runtime, management, APIs, HTTP, identity, persistence, diagnostics, scripting, scheduling, tenants, labels, resilience, and more.
src/common	Shared infrastructure such as feature/module plumbing, mediator, API helpers, and test helpers.
src/clients	Client packages, currently including the Elsa API client.
src/extensions	Extension packages that are not core modules. Currently contains Elsa.Testing.Extensions.
test/unit	Fast unit tests scoped to individual modules or services.
test/integration	In-process tests that compose multiple Elsa services.
test/component	Larger host-level and persistence-oriented scenarios.
test/performance	Benchmark and throughput-oriented tests.
build	NUKE build project and CI build wiring.
doc	ADRs, QA notes, agent logs, bounty docs, and this wiki.
specs	Spec Kit feature specs, plans, tasks, contracts, and quickstarts.
design	Logos, screenshots, and visual assets used by public docs and README files.

Major Module Families

Family	Projects	What they own
Base host package	Elsa	AddElsa, ElsaFeature, default workflow feature wiring.
Workflow engine	Elsa.Workflows.Core	Activities, execution contexts, pipelines, serialization, variables, bookmarks, graphs, flowchart primitives.
Workflow management	Elsa.Workflows.Management	Definitions, instances, stores, import/export, materializers, validation, descriptors.
Workflow runtime	Elsa.Workflows.Runtime and Elsa.Workflows.Runtime.Distributed	Dispatch, triggers, bookmark queues, runtime logs, background activity scheduling, recovery, distributed runtime support.
Alterations	Elsa.Alterations, Elsa.Alterations.Core	Bulk alteration of running workflow instances: alteration plans, jobs, dispatching, and in-memory stores; EF Core and vNext persistence packages live alongside the core.
Workflow API	Elsa.Workflows.Api and Elsa.Api.Common	FastEndpoints registration, workflow endpoints, real-time workflow updates, API serialization.
Expression languages	Elsa.Expressions, CSharp, JavaScript, Python, Liquid	Expression evaluation and language-specific activities/descriptors.
Transport/activity packages	Elsa.Http, Elsa.Http.Webhooks, Elsa.Scheduling, Elsa.Resilience	HTTP triggers and calls, outbound webhook sinks and activity-driven webhook sources (WebhooksFeature), scheduled triggers, resilience strategies.
BPMN	Elsa.Bpmn, Elsa.Bpmn.Interchange	BPMN 2.0 process execution: BpmnProcess scope activity, work ledger, scope signals; and the elsa: XML interchange format that binds BPMN document elements to Elsa activities. See bpmn-workflows.md.
Persistence (EF Core)	Elsa.Persistence.EFCore, provider packages under Elsa.Persistence.EFCore.*, and structured-log persistence packages	EF Core stores and provider-specific configuration/migrations.
Persistence vNext	Elsa.Persistence.VNext, Extensions, Runtime, Relational, Sqlite, PostgreSql, SqlServer, MongoDb	Next-generation provider-neutral persistence: module-owned storage manifests, portable document/index store, schema versioning, and physicalization for relational and document databases.
Key-value store	Elsa.KeyValues	Generic key-value storage (IKeyValueStore) with a default in-memory backing store; used by other modules for ephemeral or cross-request state.
Caching	Elsa.Caching	ICacheManager and IChangeTokenSignaler; provides memory-cache helpers and signal-based cache invalidation used internally by other Elsa modules.
Security and tenancy	Elsa.Identity, Elsa.Tenants, Elsa.Tenants.AspNetCore, Elsa.SasTokens	Users, applications, roles, API keys, tenants, tenant-aware routing, SAS tokens.
External authentication	Elsa.ExternalAuthentication, Elsa.ExternalAuthentication.OpenIdConnect, Elsa.ExternalAuthentication.Secrets, and EF Core provider packages (Sqlite, SqlServer, PostgreSql, MySql, Oracle)	Server-brokered external identity providers: Identity Provider Connections, OpenID Connect adapter, linked identity resolution, configurable unlinked-identity policies, Elsa credential issuance, and EF Core persistence. See specs/012-external-authentication/spec.md.
Secrets	Elsa.Secrets, Elsa.Secrets.Persistence.EFCore, Elsa.Secrets.Persistence.VNext, Elsa.Secrets.JavaScript	Named secrets with pluggable stores, extensible secret types (text, RSA key, X.509 certificate), versioning, rotation, revocation, secret resolver, management endpoints, EF Core and vNext persistence, and JavaScript expression access.
Diagnostics	Elsa.Diagnostics.StructuredLogs, Relational, Sqlite, Elsa.Diagnostics.ConsoleLogs	Structured ILogger capture, raw console capture, live feed, REST/SignalR endpoints, in-memory and SQLite storage.
Shells and modular hosting	Elsa.Shells.Api, CShells-facing shell feature classes throughout modules	Runtime-configurable feature loading for modular hosts.
Operational dashboard	Elsa.Dashboard.Api	Read-only aggregate endpoints for the Studio operational dashboard: overview, trends, needs-attention findings, recent activity, and workflow hotspots.
Application clustering	Elsa.Hosting.Management	Application instance naming, heartbeat-based cluster membership, and instance-aware hosted service support for multi-node deployments.
AI / Weaver	Elsa.AI.Abstractions, Elsa.AI.Copilot, Elsa.AI.Host, Elsa.AI.Persistence.EFCore	Weaver AI copilot: streaming chat, context resolution, reviewable proposals, audit, and provider abstraction for AI-assisted workflow authoring.

Reference Hosts

• Elsa.Server.Web is the most useful all-up ASP.NET Core sample. Its Program.cs shows typical module composition with identity, EF Core SQLite, runtime, management, HTTP, scheduling, scripting, multitenancy, and optional structured logs.
• Elsa.ModularServer.Web demonstrates modular package loading through Nuplane and shell features.
• Elsa.Server.LoadBalancer is a load-balancer host.
• Elsa.SamplePackage is a minimal package-style feature sample.

Build And Package Files

• Directory.Build.props contains shared MSBuild settings.
• src/Directory.Build.props multi-targets source packages for net8.0, net9.0, and net10.0.
• Directory.Packages.props centrally manages package versions, including conditional versions for .NET 8/9 versus .NET 10.
• build/Build.cs defines the NUKE build, test, and package targets.

How To Find Code Fast

Use the feature class first. Most modules have a Features/*Feature.cs and often a parallel ShellFeatures/*Feature.cs. The feature class tells you what the module registers and what other features it depends on. After that, follow contracts and service registrations into implementation files.

Good first searches:

rg "class .*Feature" src/modules src/common
rg "interface I.*Store" src/modules
rg "AddScoped|AddSingleton|TryAdd" src/modules/Elsa.Workflows.Runtime/Features
rg "Get\\(|Post\\(|Delete\\(" src/modules/Elsa.Workflows.Api/Endpoints