# azure/azure-functions-durable-extension architecture

> Architecture diagram of the GitHub repository azure/azure-functions-durable-extension, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azure/azure-functions-durable-extension
- Repository: https://github.com/azure/azure-functions-durable-extension

## Overview

##### Project type and purpose
- This is an open-source extension library (“Durable Functions”) for the Azure Functions platform.
- Its purpose is to add stateful workflow primitives (orchestrators, activities, entities) into the Azure Functions host by providing bindings, listeners, context implementations, storage providers, HTTP/GRPC APIs, and compile-time analyzers/source generators.

##### File structure
- src/WebJobs.Extensions.DurableTask – the core runtime library loaded into the Functions host
– Bindings: ActivityTrigger, OrchestrationTrigger, EntityTrigger
– ContextImplementations: DurableOrchestrationContext, DurableActivityContext, DurableEntityContext, DurableClient
– Listener: DurableTaskListener, GRPC listener for out-of-proc scenarios
– Storage: Azure Storage / Queue / Table / Blob providers for histories, messages, payloads
– HTTP: HTTP API handler for management endpoints
– Correlation & Telemetry helpers
- src/Worker.Extensions.DurableTask – the .NET Functions Worker (isolated process) integration
- src/WebJobs.Extensions.DurableTask.Analyzers – Roslyn analyzers and code-fix providers for C# functions
- src/DurableFunctions.TypedInterfaces – a source-generator that emits strongly-typed Durable Function client and activity callers at compile time
- test & samples – a large suite of unit, smoke, E2E, performance tests and sample projects demonstrating usage
- docfx & docs – documentation site generator and built API reference

##### README for additional insights
- Confirms the extension model: it plugs into Azure Functions to enable orchestrator, activity, and entity functions
- References the core NuGet packages and supported languages

##### Main components
a. Azure Functions Host
– The “WebJobs Host” or “Functions Worker” which loads extensions at startup.
b. Durable Functions Extension (your code under src/)
– Bindings registration
– Listeners (polling storage, handling GRPC for out-of-proc)
– Context implementations (in-proc and out-of-proc)
– Storage providers (Queue, Table, Blob)
– HTTP Management API
– Telemetry & Correlation
c. Developer’s Function Code
– Orchestrator functions
– Activity functions
– Entity functions
d. Azure Storage Services
– Queues: orchestration messages
– Tables: status & history
– Blobs: large payloads
e. HTTP / GRPC Client
– Client code calling StartNewAsync, RaiseEvent, QueryStatus (via HTTP or language SDK)
f. Compile-time toolchain
– Roslyn Analyzers for C# rules
– Source Generator for typed interfaces

##### Relationships and interactions
- At startup, Functions Host → invokes DurableTaskWebJobsStartup → registers binding providers & listeners
- Developer’s code decorated with [OrchestrationTrigger], [ActivityTrigger], [EntityTrigger]
- Host listens on Storage Queues or gRPC ports → dispatches to orchestrator/activity/entity contexts
- Context implementations enqueue messages into storage (Queues/Tables/Blobs) and manage state transitions
- HTTP Management API sits on top of Functions Host → exposes REST endpoints for client control
- Telemetry & correlation modules hook into ActivitySource/ILogger → push to Application Insights
- During build, source generator runs → emits typed callers; analyzers validate attribute usage

##### Architectural patterns & design principles
- Extension-based plugin model (Functions extensibility)
- Publisher-subscriber messaging via storage queues
- Stateful workflows implemented as deterministic event-sourced orchestrators
- Out-of-proc isolation via gRPC bridging
- Dependency Injection and options pattern for configuration
- Compile-time code generation (source generators) and static analysis

##### Essential elements to capture
- The Functions Host extension hook
- Storage-based messaging backbone
- Context implementations bridging host and storage
- HTTP Management API layer
- Out-of-proc gRPC channel for isolated worker
- Compile-time Roslyn pipeline (analyzers, source generator)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-time Tools
    subgraph "Build-time Tools"
        direction TB
        Analyzers["Roslyn Analyzers"]:::compiletime
        Generator["Source Generators"]:::compiletime
    end

    %% Runtime Extension in Functions Host
    subgraph "Runtime Extension"
        direction TB
        Host["Azure Functions Host"]:::host
        subgraph "Durable Functions Extension"
            direction TB
            Startup["DurableTaskWebJobsStartup"]:::runtime
            Bindings["Trigger Binding Providers"]:::runtime
            Listener["DurableTaskListener & Scale Monitor"]:::runtime
            GRPCListener["gRPC Listener"]:::runtime
            Contexts["Context Implementations"]:::runtime
            StorageProviders["Storage Providers"]:::runtime
            HttpApi["HTTP Management API"]:::runtime
            Telemetry["Correlation & Telemetry Helpers"]:::runtime
        end
    end

    %% External Services & Developer Code
    subgraph "External & Developer"
        direction TB
        subgraph "Developer Functions"
            direction TB
            Orchestrator["Orchestrator Functions"]:::developer
            Activity["Activity Functions"]:::developer
            Entity["Entity Functions"]:::developer
        end
        subgraph "Clients"
            direction TB
            HTTPClient["HTTP Client"]:::external
            GRPCClient["gRPC Client"]:::external
        end
        subgraph "Azure Storage"
            direction TB
            Queues["Queues"]:::azure
            Tables["Tables"]:::azure
            Blobs["Blobs"]:::azure
        end
        AppInsights["Application Insights"]:::azure
    end

    %% Connections
    Analyzers -->|analyze code| Generator
    Generator -->|emit typed callers| DeveloperInterfaces

    Host -->|load extension| Startup
    Startup -->|register| Bindings
    Startup -->|register| Listener
    Startup -->|register| GRPCListener
    Bindings -->|provide triggers| Host
    Listener -->|dispatch events| Contexts
    GRPCListener -->|dispatch events| Contexts

    Host -->|invoke via triggers| Orchestrator
    Host -->|invoke via triggers| Activity
    Host -->|invoke via triggers| Entity

    Contexts -->|enqueue/dequeue via| Queues
    Contexts -->|persist history in| Tables
    Contexts -->|store payloads in| Blobs

    HTTPClient -->|HTTP| HttpApi
    HttpApi -->|invoke| Host

    GRPCClient -->|gRPC| GRPCListener

    Telemetry -->|push metrics| AppInsights
    Contexts -->|log via| Telemetry

    %% Click Events
    click Startup "https://github.com/azure/azure-functions-durable-extension/blob/dev/src/WebJobs.Extensions.DurableTask/DurableTaskWebJobsStartup.cs"
    click Bindings "https://github.com/azure/azure-functions-durable-extension/tree/dev/src/WebJobs.Extensions.DurableTask/Bindings"
    click Listener "https://github.com/azure/azure-functions-durable-extension/tree/dev/src/WebJobs.Extensions.DurableTask/Listener"
    click GRPCListener "https://github.com/azure/azure-functions-durable-extension/tree/dev/src/WebJobs.Extensions.DurableTask/Grpc"
    click Contexts "https://github.com/azure/azure-functions-durable-extension/tree/dev/src/WebJobs.Extensions.DurableTask/ContextImplementations"
    click StorageProviders "https://github.com/azure/azure-functions-durable-extension/blob/dev/src/WebJobs.Extensions.DurableTask/AzureStorageDurabilityProvider.cs"
    click HttpApi "https://github.com/azure/azure-functions-durable-extension/blob/dev/src/WebJobs.Extensions.DurableTask/HttpApiHandler.cs"
    click Telemetry "https://github.com/azure/azure-functions-durable-extension/tree/dev/src/WebJobs.Extensions.DurableTask/Correlation"
    click Analyzers "https://github.com/azure/azure-functions-durable-extension/blob/dev/src/WebJobs.Extensions.DurableTask.Analyzers"
    click Generator "https://github.com/azure/azure-functions-durable-extension/tree/dev/src/DurableFunctions.TypedInterfaces/SourceGenerator"
    click HTTPClient "https://github.com/azure/azure-functions-durable-extension/blob/dev/src/WebJobs.Extensions.DurableTask/TypedDurableClientBindingProvider.cs"
    click HTTPClient "https://github.com/azure/azure-functions-durable-extension/blob/dev/src/WebJobs.Extensions.DurableTask/DurableClientAttribute.cs"
    click DeveloperInterfaces "https://github.com/azure/azure-functions-durable-extension/tree/dev/src/WebJobs.Extensions.DurableTask/ContextInterfaces"

    %% Styles
    classDef compiletime fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef runtime fill:#C7E9B4,stroke:#333,stroke-width:1px
    classDef azure fill:#A6CEE3,stroke:#333,stroke-width:1px
    classDef developer fill:#FDBF6F,stroke:#333,stroke-width:1px
    classDef host fill:#B2DF8A,stroke:#333,stroke-width:1px
    class Analyzers,Generator compiletime
    class Host host
    class Startup,Bindings,Listener,GRPCListener,Contexts,StorageProviders,HttpApi,Telemetry runtime
    class Queues,Tables,Blobs,AppInsights azure
    class Orchestrator,Activity,Entity developer
    class HTTPClient,GRPCClient external
```
