# microsoft/duroxide architecture

> Architecture diagram of the GitHub repository microsoft/duroxide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/duroxide
- Repository: https://github.com/microsoft/duroxide

## Overview

Duroxide is an embeddable Rust durable-execution runtime. A caller starts an orchestration through the client; the runtime dispatches orchestration work, replays recorded history, and runs registered activities, while a provider persists history and work. The runtime also exposes observability, and the repository includes SQLite storage plus reusable provider-conformance and stress-test utilities. README descriptions establish the user workflow; several internal connections rely on the source index, so unsampled implementation details are not inferred beyond those references.

Main entry points: [`src/providers/mod.rs`](https://github.com/microsoft/duroxide/blob/main/src/providers/mod.rs) (Provider Contract), [`src/runtime/mod.rs`](https://github.com/microsoft/duroxide/blob/main/src/runtime/mod.rs) (Runtime), [`src/runtime/dispatchers/orchestration.rs`](https://github.com/microsoft/duroxide/blob/main/src/runtime/dispatchers/orchestration.rs) (Orchestration Dispatcher), [`src/provider_stress_test/core.rs`](https://github.com/microsoft/duroxide/blob/main/src/provider_stress_test/core.rs) (Provider Stress Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Workflow API"]
  node_client["Client API<br/>[mod.rs]"]
  node_workflow_context["Workflow Primitives<br/>[lib.rs]"]
  node_combinators["Async Combinators<br/>[combinators.rs]"]
end

subgraph group_runtime["Execution Runtime"]
  node_runtime_core["Runtime<br/>[mod.rs]"]
  node_registry["Handler Registry<br/>[registry.rs]"]
  node_orchestration_dispatcher["Orchestration Dispatcher<br/>[orchestration.rs]"]
  node_worker_dispatcher["Worker Dispatcher<br/>[worker.rs]"]
  node_execution["Execution Engine<br/>[execution.rs]"]
  node_replay["Replay Engine<br/>[replay_engine.rs]"]
  node_state["Runtime State<br/>[state_helpers.rs]"]
  node_observability["Observability<br/>[observability.rs]"]
end

subgraph group_storage["Persistence"]
  node_provider_trait["Provider Contract<br/>[mod.rs]"]
  node_sqlite[("SQLite Provider<br/>[sqlite.rs]")]
  node_instrumented["Instrumented Provider<br/>[instrumented.rs]"]
end

subgraph group_provider_tools["Provider Utilities"]
  node_provider_validation["Provider Validation"]
  node_validation_exports["Validation Utilities"]
  node_stress_tests["Provider Stress Tests<br/>[core.rs]"]
end

node_caller(("Application"))

node_caller -->|"starts workflows"| node_client
node_client -->|"submits requests"| node_provider_trait
node_runtime_core -->|"starts dispatchers"| node_orchestration_dispatcher
node_runtime_core -->|"starts dispatchers"| node_worker_dispatcher
node_runtime_core -->|"uses registrations"| node_registry
node_orchestration_dispatcher -->|"fetches work"| node_provider_trait
node_worker_dispatcher -->|"fetches work"| node_provider_trait
node_orchestration_dispatcher -->|"runs replay"| node_replay
node_execution -.->|"persists execution"| node_provider_trait
node_replay -->|"uses provider"| node_provider_trait
node_runtime_core -->|"records metrics"| node_observability
node_instrumented -->|"records metrics"| node_observability
node_sqlite -->|"implements contract"| node_provider_trait
node_validation_exports -->|"re-exports tests"| node_provider_validation
node_provider_validation -->|"checks behavior"| node_provider_trait
node_stress_tests -->|"runs workloads"| node_runtime_core
node_stress_tests -->|"accepts providers"| node_provider_trait

click node_client "https://github.com/microsoft/duroxide/blob/main/src/client/mod.rs"
click node_workflow_context "https://github.com/microsoft/duroxide/blob/main/src/lib.rs"
click node_combinators "https://github.com/microsoft/duroxide/blob/main/src/combinators.rs"
click node_runtime_core "https://github.com/microsoft/duroxide/blob/main/src/runtime/mod.rs"
click node_registry "https://github.com/microsoft/duroxide/blob/main/src/runtime/registry.rs"
click node_orchestration_dispatcher "https://github.com/microsoft/duroxide/blob/main/src/runtime/dispatchers/orchestration.rs"
click node_worker_dispatcher "https://github.com/microsoft/duroxide/blob/main/src/runtime/dispatchers/worker.rs"
click node_execution "https://github.com/microsoft/duroxide/blob/main/src/runtime/execution.rs"
click node_replay "https://github.com/microsoft/duroxide/blob/main/src/runtime/replay_engine.rs"
click node_state "https://github.com/microsoft/duroxide/blob/main/src/runtime/state_helpers.rs"
click node_observability "https://github.com/microsoft/duroxide/blob/main/src/runtime/observability.rs"
click node_provider_trait "https://github.com/microsoft/duroxide/blob/main/src/providers/mod.rs"
click node_sqlite "https://github.com/microsoft/duroxide/blob/main/src/providers/sqlite.rs"
click node_instrumented "https://github.com/microsoft/duroxide/blob/main/src/providers/instrumented.rs"
click node_provider_validation "https://github.com/microsoft/duroxide/tree/main/src/provider_validation"
click node_validation_exports "https://github.com/microsoft/duroxide/blob/main/src/provider_validations.rs"
click node_stress_tests "https://github.com/microsoft/duroxide/blob/main/src/provider_stress_test/core.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_workflow_context,node_combinators toneBlue
class node_runtime_core,node_registry,node_orchestration_dispatcher,node_worker_dispatcher,node_execution,node_replay,node_state,node_observability toneAmber
class node_provider_trait,node_sqlite,node_instrumented toneMint
class node_provider_validation,node_validation_exports,node_stress_tests toneRose
class node_caller toneIndigo
```

## Components

### Workflow API

- [Client API](https://github.com/microsoft/duroxide/blob/main/src/client/mod.rs): `src/client/mod.rs`
- [Workflow Primitives](https://github.com/microsoft/duroxide/blob/main/src/lib.rs): `src/lib.rs`
- [Async Combinators](https://github.com/microsoft/duroxide/blob/main/src/combinators.rs): `src/combinators.rs`

### Execution Runtime

- [Runtime](https://github.com/microsoft/duroxide/blob/main/src/runtime/mod.rs): `src/runtime/mod.rs`
- [Handler Registry](https://github.com/microsoft/duroxide/blob/main/src/runtime/registry.rs): `src/runtime/registry.rs`
- [Orchestration Dispatcher](https://github.com/microsoft/duroxide/blob/main/src/runtime/dispatchers/orchestration.rs): `src/runtime/dispatchers/orchestration.rs`
- [Worker Dispatcher](https://github.com/microsoft/duroxide/blob/main/src/runtime/dispatchers/worker.rs): `src/runtime/dispatchers/worker.rs`
- [Execution Engine](https://github.com/microsoft/duroxide/blob/main/src/runtime/execution.rs): `src/runtime/execution.rs`
- [Replay Engine](https://github.com/microsoft/duroxide/blob/main/src/runtime/replay_engine.rs): `src/runtime/replay_engine.rs`
- [Runtime State](https://github.com/microsoft/duroxide/blob/main/src/runtime/state_helpers.rs): `src/runtime/state_helpers.rs`
- [Observability](https://github.com/microsoft/duroxide/blob/main/src/runtime/observability.rs): `src/runtime/observability.rs`

### Persistence

- [Provider Contract](https://github.com/microsoft/duroxide/blob/main/src/providers/mod.rs): `src/providers/mod.rs`
- [SQLite Provider](https://github.com/microsoft/duroxide/blob/main/src/providers/sqlite.rs): `src/providers/sqlite.rs`
- [Instrumented Provider](https://github.com/microsoft/duroxide/blob/main/src/providers/instrumented.rs): `src/providers/instrumented.rs`

### Provider Utilities

- [Provider Validation](https://github.com/microsoft/duroxide/tree/main/src/provider_validation): `src/provider_validation`
- [Validation Utilities](https://github.com/microsoft/duroxide/blob/main/src/provider_validations.rs): `src/provider_validations.rs`
- [Provider Stress Tests](https://github.com/microsoft/duroxide/blob/main/src/provider_stress_test/core.rs): `src/provider_stress_test/core.rs`

### Other components

- **Application**

## Connections

- Application → Client API: starts workflows
- Client API → Provider Contract: submits requests (evidence: `src/client/mod.rs`)
- Runtime → Orchestration Dispatcher: starts dispatchers (evidence: `src/runtime/mod.rs`)
- Runtime → Worker Dispatcher: starts dispatchers (evidence: `src/runtime/mod.rs`)
- Runtime → Handler Registry: uses registrations (evidence: `src/runtime/mod.rs`)
- Orchestration Dispatcher → Provider Contract: fetches work (evidence: `src/runtime/dispatchers/orchestration.rs`)
- Worker Dispatcher → Provider Contract: fetches work (evidence: `src/runtime/dispatchers/worker.rs`)
- Orchestration Dispatcher → Replay Engine: runs replay
- Execution Engine → Provider Contract: persists execution
- Replay Engine → Provider Contract: uses provider (evidence: `src/runtime/replay_engine.rs`)
- Runtime → Observability: records metrics (evidence: `src/runtime/mod.rs`)
- Instrumented Provider → Observability: records metrics (evidence: `src/providers/instrumented.rs`)
- SQLite Provider → Provider Contract: implements contract (evidence: `src/providers/sqlite.rs`)
- Validation Utilities → Provider Validation: re-exports tests (evidence: `src/provider_validations.rs`)
- Provider Validation → Provider Contract: checks behavior (evidence: `src/provider_validation/mod.rs`)
- Provider Stress Tests → Runtime: runs workloads (evidence: `src/provider_stress_test/core.rs`)
- Provider Stress Tests → Provider Contract: accepts providers (evidence: `src/provider_stress_test/core.rs`)
