# Serdica Workflow Engine Architecture

## Purpose

This folder defines the target architecture for the workflow engine runtime.

The design in this folder assumes:

- authored C# workflow classes remain the source of truth
- workflows are already fully declarative and can be compiled to canonical definitions
- the service will run a single engine provider per deployment
- migration and concurrent engine execution are out of scope for v1
- Oracle is the durable system of record
- Oracle Advanced Queuing is the default signaling and scheduling backend
- Redis is optional and not on the correctness path

This package is intentionally detailed. It documents engine behavior, persistence, signaling, and runtime structure. Platform transport and command-mapping details are outside its scope.

## Reading Order

1. [01-requirements-and-principles.md](01-requirements-and-principles.md)
2. [02-runtime-and-component-architecture.md](02-runtime-and-component-architecture.md)
3. [03-canonical-execution-model.md](03-canonical-execution-model.md)
4. [04-persistence-signaling-and-scheduling.md](04-persistence-signaling-and-scheduling.md)
5. [05-service-surface-hosting-and-operations.md](05-service-surface-hosting-and-operations.md)
6. [06-implementation-structure.md](06-implementation-structure.md)
7. [07-sprint-plan.md](07-sprint-plan.md)
8. [08-load-and-performance-plan.md](08-load-and-performance-plan.md)
9. [09-backend-portability-plan.md](09-backend-portability-plan.md)
10. [10-oracle-performance-baseline-2026-03-17.md](10-oracle-performance-baseline-2026-03-17.md)
11. [11-postgres-performance-baseline-2026-03-17.md](11-postgres-performance-baseline-2026-03-17.md)
12. [12-mongo-performance-baseline-2026-03-17.md](12-mongo-performance-baseline-2026-03-17.md)
13. [13-backend-comparison-2026-03-17.md](13-backend-comparison-2026-03-17.md)
14. [14-signal-driver-backend-matrix-2026-03-17.md](14-signal-driver-backend-matrix-2026-03-17.md)
15. [15-backend-and-signal-driver-usage.md](15-backend-and-signal-driver-usage.md)

## Executive Summary

The engine is designed around six core decisions:

1. Workflow execution moves from the earlier runtime to a canonical interpreter owned by the engine.
2. The interpreter executes canonical workflow definitions compiled from authored C# workflows.
3. Oracle remains the single durable source of truth for workflow runtime state, projections, and host coordination.
4. Oracle AQ provides durable signaling and scheduling with blocking dequeue semantics, which removes polling from the steady-state engine path.
5. The engine uses a run-to-wait model: an instance is loaded, advanced until the next wait boundary, persisted, and released. No node permanently owns an instance.
6. The workflow service surface remains stable. The engine is a runtime replacement, not a transport or UI rewrite.

## Scope Summary

### In Scope

- start workflow
- activate human tasks
- assign, release, and complete tasks
- execute canonical transport calls
- execute canonical conditions, loops, branches, and subworkflows
- schedule delayed resumes and retry wakes without polling
- resume safely after node, service, or full-cluster restart
- support multi-instance deployment with one shared database
- preserve read-side service contracts, projections, authorization, diagrams, retention, and canonical inspection

### Out of Scope

- concurrent old-runtime and engine execution
- in-place instance migration between engines
- Redis as a correctness-grade signaling dependency
- user-facing workflow authoring changes
- replacing the public workflow service surface

## Product Position

At the workflow-service boundary, the runtime still has to support:

- workflow and task operations
- the task inbox and assignment system
- the workflow diagram provider
- canonical definition and validation access
- the operational retention owner

The engine is a runtime subsystem under the workflow service, not a separate product.

## Design Baseline

The engine architecture in this folder should be treated as the default implementation plan unless a later ADR explicitly replaces part of it.