# EventConductor > Event-driven workflow / saga orchestration engine for Java/Spring. Describe a business process as a workflow definition (YAML or JSON) made of steps; the engine drives the state machine, retries, timeouts and compensation, and delegates business logic to stateless workers or built-in steps (HTTP_CALL, LLM_CALL, PUBLISH_EVENT). Scales from a single in-process JVM (no Kafka, no DB) to a multi-pod cluster (Kafka + PostgreSQL) with no change to business code. Two properties select the topology: `workflow.mode` (`embedded` | `kafka`, default `embedded`) and `workflow.persistence` (`memory` | `jpa`, default `memory`). Artifacts are on Maven Central under `io.mateu.workflow` (`workflow-engine`, `workflow-test`, `workflow-maven-plugin`, `forms-engine`, `rule-engine`, `rule-runtime`, `worker-embedded`, `worker-kafka`, `worker-http`, `worker-llm`, `inbound-events-kafka`, …), one version for all. Secure by default: the REST API needs an API key or Spring Security, the consoles and MCP need Spring Security (`workflow.message-api.allow-anonymous=true` for local development only). ## AI reference files - [Compact reference](https://raw.githubusercontent.com/miguelperezcolom/eventconductor/main/doc/public/eventconductor-ai-compact.md): setup, DSL rules, decision guide, step types, workers, testing, REST/MCP, security, gotchas. Fits a context window; use for day-to-day generation. - [Full reference](https://raw.githubusercontent.com/miguelperezcolom/eventconductor/main/doc/public/eventconductor-ai-full.md): everything — every step and field, deployment modes, Kafka, Java API, operations, security, upgrade notes 2.27 → 2.33. - [Claude Code skills](https://github.com/miguelperezcolom/eventconductor/tree/main/.claude/skills): `eventconductor` (definitions, patterns, testing, workers, operations, security, gotchas), `eventconductor-scaffold` (new project), `eventconductor-run` (run and verify). Copy `.claude/skills/eventconductor*` into your project's `.claude/skills/`. - [Validated patterns](https://raw.githubusercontent.com/miguelperezcolom/eventconductor/main/.claude/skills/eventconductor/reference/patterns.md): saga with timer, human approval, HTTP integration, event-triggered flow, request/response, forEach fan-out, polling, LLM call, updates, flow control, child process, sensitive data. Every example is checked by the build against the schema and the engine. - [Workflow definition JSON Schema](https://raw.githubusercontent.com/miguelperezcolom/eventconductor/main/modules/workflow-engine/src/main/resources/workflow-definition-schema.json): editor autocomplete and validation (also `events-schema.json`, `cron-schema.json`). - [OpenAPI of /workflow/api](https://raw.githubusercontent.com/miguelperezcolom/eventconductor/main/doc/public/openapi/eventconductor-api.yaml). ## Guides - [Introduction](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/introduction.md): what EventConductor is and why - [Quick Start](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/quickstart.mdx): first workflow in minutes, fully embedded - [Deployment Modes](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/deployment-modes.md): embedded/memory → embedded/jpa → kafka/jpa; secure defaults; Flyway - [Workflow Definitions](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/workflow-definitions.md): the YAML/JSON DSL, retention, tags, git-import, working copies - [Starting a Process](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/starting-a-process.md): create/pause/resume/cancel/query processes, variables - [Implementing Workers](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/workers.md): task contracts and generated handlers, embedded and Kafka workers, WorkerReply - [HTTP Workers](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/http-workers.md): workers in any language over /workflow/api/workers; Python SDK - [Retries, Timeouts & Compensation](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/retries-timeouts-compensation.md): sagas, COMPENSATED / COMPENSATION_FAILED - [Loops and Multi-Instance](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/loops-and-multi-instance.md): forEach, repeat, loopBack - [Scheduling and Deadlines](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/scheduling-and-deadlines.md): TIMER until moments, deadlines, schedules - [Asynchronous Request/Response](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/request-response.md): EC answering requests; awaitReply to ask and wait without losing fast replies - [Synchronous Invocation](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/synchronous-invocation.md): start over HTTP and wait for the REPLY - [Updating Running Processes](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/updating-running-processes.md): named, validated updates and update-with-start - [Flow Control](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/flow-control.md): startPolicy (debounce/throttle/singleton), worker rate limits, priority - [Long-Running Processes](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/long-running-processes.md): CONTINUE_AS_NEW and businessKeyPolicy - [HTTP Calls](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/http-calls.md): HTTP_CALL, connections, auth profiles, host-bound credentials, secrets - [LLM Calls](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/llm-calls.md): LLM_CALL with Spring AI (Anthropic / OpenAI-compatible) - [Agents in Workflows](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/workflow-agents.md): the AGENT step — agents published in the IA catalogue, run by the IA runtime, durable invocations and review holds - [Publishing Events](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/publishing-events.md): PUBLISH_EVENT through the built-in publish-event task, CloudEvents - [Domain Event Triggers](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/domain-event-triggers.md): triggers, events.yaml, onEvent waits - [Webhooks](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/webhooks.md): the webhook gateway: GitHub / HMAC deliveries as CloudEvents - [Payload Templates](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/payload-templates.md): ${…} templates for HTTP, events, replies - [User Tasks](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/user-tasks.md): USER_TASK and form executions - [Human Tasks: Assignment and Escalation](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/human-tasks-assignment-and-escalation.md): assignee, candidates, priority, due dates, escalation, task inbox - [Form Definitions](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/form-definitions.md): forms for user tasks - [Rule Definitions](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/rule-definitions.md): expression rules and decision tables - [Rule Evaluation](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/rule-evaluation.md): embedding the rule runtime, RULE steps - [Testing Workflows](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/testing-workflows.md): workflow-test: @EventConductorTest, mocks, HTTP/LLM stubs, advanceTime, assertions - [Test Worker](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/test-worker.md): drive a deployment through any outcome with TEST_CONFIG - [Operating Running Processes](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/operating-running-processes.md): set variables, complete a step, retry from a step, incidents, audit - [Searching and Bulk Operations](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/searching-and-bulk-operations.md): search attributes, query language, batch operations - [Migrating Running Processes](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/migrating-running-processes.md): move live processes to another version; check-migration in CI - [Sensitive Data and Encryption](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/sensitive-data-and-encryption.md): sensitiveVariables, encryption keys, masking, audited reveal - [Reliability](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/reliability.md): what survives pod/DB/broker failures; Kafka redelivery - [Sharding](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/sharding.md): shared-nothing shards for write scale - [Process Analytics](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/analytics.md): counts, rates, durations, bottlenecks - [MCP Overview](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/mcp-overview.md): operate the engine from AI agents - [MCP with Claude Desktop](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/mcp-claude-desktop.md): connect Claude Desktop - [IDE Plugins](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/guides/ide-plugins.md): VS Code / IntelliJ graph editor and schema validation ## Reference - [Step Types](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/reference/step-types.md): every step type and field - [Statuses](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/reference/statuses.md): process and step statuses - [Configuration](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/reference/configuration.md): all properties; HTTP security; consumer redelivery - [Processes REST API](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/reference/processes-rest-api.md): /workflow/api/processes and friends - [HTTP Worker API](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/reference/http-worker-api.md): the long-poll worker protocol - [Maven Plugin](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/reference/maven-plugin.md): validate, check-migration, verify (all checks + coverage floors, for CI), generate-worker-sources - [Task Contracts](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/reference/task-contracts.md): the .ectask format and the wire protocol - [Kafka Topics](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/reference/kafka-topics.md): topics, consumer groups, redelivery and offsets - [Observability](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/reference/observability.md): metrics and tracing - [Versioning](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/reference/versioning.md): what is stable - [Java API](https://github.com/miguelperezcolom/eventconductor/blob/main/doc/src/content/docs/reference/java-api.mdx): public beans and records ## Key rules for generating definitions - Every step has `id`, `type` and `name`; unknown keys are refused by the schema. - At most one `START`; every other step needs a precondition (`preconditionStepId`, `preconditionStepIds`, or `preconditions: [{stepId, expression, onFalse}]`) — except compensation steps and a `WAIT_FOR_MESSAGE` that begins a flow. - Steps run by data flow, never array order; no precondition cycles (use `forEach`, `repeat`, `loopBack`). - One `END`; converge FORK branches with an AND `JOIN`, CHOICE branches with `joinType: XOR`. - Saga: `compensable: true` + `compensationStepId`; compensation steps have no preconditions. - Ask-and-wait: `awaitReply` on the HTTP_CALL / PUBLISH_EVENT, not a WAIT_FOR_MESSAGE after it. - No credentials in definitions: HTTP via `workflow.http.connections` / `workflow.http.auth.` / `${secret:NAME}`, LLM keys in `workflow.llm.connections`. - Validate with `mvn eventconductor:validate`; test with `@EventConductorTest` (`io.mateu.workflow:workflow-test`).