# microsoft/service-fabric-services-and-actors-dotnet architecture

> Architecture diagram of the GitHub repository microsoft/service-fabric-services-and-actors-dotnet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/service-fabric-services-and-actors-dotnet
- Repository: https://github.com/microsoft/service-fabric-services-and-actors-dotnet

## Overview

##### Project Type and Purpose
- The project is a set of framework libraries – not a front–end application – that provide developers with the APIs to build fault–tolerant, scalable applications on Azure Service Fabric.
- It covers two primary paradigms: Reliable Actors (based on the Virtual Actor model) and Reliable Services (light–weight service framework) with multiple remoting options (native remoting, WCF, and even legacy support).

##### File Structure
- The top–level directories include configuration files (build scripts, GitHub workflows, licensing, etc.), a “src” directory that contains the C# projects, and a “test” directory for unit tests.
- Within “src”, the code is further subdivided into several project groups:
– “FabActUtil” which provides utilities for Service Fabric Actors.
– “Microsoft.ServiceFabric.Actors” and “Microsoft.ServiceFabric.Actors.Wcf” for core actor logic and remoting.
– “Microsoft.ServiceFabric.Actors.KVSToRCMigration” contains components to support migration scenarios.
– “Microsoft.ServiceFabric.Services.Remoting”, “Microsoft.ServiceFabric.Services.Wcf”, and “Microsoft.ServiceFabric.Services” that target Reliable Services and their communication layers.
– “netstandard” which shows cross–platform compatibility implementations.
- Additional directories such as “nuprojs”, “properties”, “nuget”, and various build scripts indicate a robust build and packaging process.

##### Key Components
a. Actors Component:
– Core Actors Framework (Microsoft.ServiceFabric.Actors).
– Actor Client and Remoting layers (including remoting V2 and WCF integration).
– Migration sub–components (for handling ambiguous actor IDs and state migration).
– Utilities (such as FabActUtil) that support actor generation, command line parsing, and configuration updates.

b. Services Component:
– Reliable Services Framework (Microsoft.ServiceFabric.Services).
– Service Remoting (both native and via WCF, including remoting V2).
– Communication sub–systems (clients, retry policies, communication listeners).

c. Cross–cutting Concerns:
– Diagnostics and Telemetry (various “Diagnostics” folders across the projects).
– Build & Packaging (build.ps1, CI workflows, and NuGet packaging).
– Testing, which is expressed in the “test” directory.

##### Relationships and Interactions
- Separation of Reliable Services and how they similarly expose communication interfaces (remoting, WCF) and integrate with Service Fabric’s state management.
- Migration components that handle state or actor ID ambiguities, interacting closely with both Actors and underlying state providers.
- Sharing of underlying infrastructure such as runtime (state providers, communication listeners), diagnostic modules, and serialization/serialization utilities.

##### Architectural Patterns and Design Principles
- Layered architecture where low–level communication (remoting, fabric transport) is abstracted away from the service and actor business logic.
- The modular design is reflected in having different projects for different protocols (native remoting vs. WCF vs. migration), highlighting the Single Responsibility Principle and separation of concerns.
- Use of dependency injection and extensibility points (for custom serializers, exception converters, etc.) especially in remoting and migration pipelines.

##### Detail Level
– It should be detailed enough that someone new to the repository could quickly understand how the various Service Fabric packages interrelate, how clients interact with them, and where custom extension points exist.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Consumer
    Client["Client Application"]:::external

    %% Actors Framework Subgraph
    subgraph "Actors Framework"
        ActorsCore["Microsoft.ServiceFabric.Actors - Core"]:::actorLib
        ActorsRemV2["Actors Remoting V2"]:::communicator
        ActorsRemWCF["Actors Remoting WCF"]:::communicator
        ActorsMigration["Actors Migration Components"]:::actorLib
        ActorsUtil["Actors Utilities"]:::actorLib
    end

    %% Services Framework Subgraph
    subgraph "Services Framework"
        ServicesCore["Microsoft.ServiceFabric.Services - Core"]:::serviceLib
        ServicesRemNative["Services Remoting (Native)"]:::communicator
        ServicesRemWCF["Services Remoting (WCF)"]:::communicator
        ServicesComm["Services Communication Clients"]:::communicator
    end

    %% Cross-Cutting Subgraph
    subgraph "Cross-Cutting"
        BuildPack["Build & Packaging"]:::build
        Testing["Testing"]:::testing
    end

    %% External calls from Client to communication layers
    Client -->|"calls"| ActorsRemV2
    Client -->|"calls"| ActorsRemWCF
    Client -->|"calls"| ServicesComm

    %% Actors internal flow
    ActorsRemV2 -->|"forwards"| ActorsCore
    ActorsRemWCF -->|"forwards"| ActorsCore
    ActorsUtil -->|"supports"| ActorsCore
    ActorsMigration -->|"migrates"| ActorsCore

    %% Services internal flow
    ServicesRemNative -->|"calls"| ServicesCore
    ServicesRemWCF -->|"calls"| ServicesCore
    ServicesComm -->|"calls"| ServicesCore

    %% Cross-Cutting interactions
    BuildPack -->|"builds"| ActorsCore
    BuildPack -->|"builds"| ServicesCore
    Testing -->|"validates"| ActorsCore
    Testing -->|"validates"| ServicesCore

    %% Class Definitions
    classDef actorLib fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef serviceLib fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef communicator fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef build fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef testing fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#E8F8F5,stroke:#117864,stroke-width:2px,stroke-dasharray: 5 5;

    %% Click Events for Component Mapping
    click ActorsCore "https://github.com/microsoft/service-fabric-services-and-actors-dotnet/blob/develop/src/Microsoft.ServiceFabric.Actors"
    click ActorsRemV2 "https://github.com/microsoft/service-fabric-services-and-actors-dotnet/tree/develop/src/Microsoft.ServiceFabric.Actors/Remoting/V2"
    click ActorsRemWCF "https://github.com/microsoft/service-fabric-services-and-actors-dotnet/blob/develop/src/Microsoft.ServiceFabric.Actors.Wcf"
    click ActorsMigration "https://github.com/microsoft/service-fabric-services-and-actors-dotnet/blob/develop/src/Microsoft.ServiceFabric.Actors.KVSToRCMigration"
    click ActorsUtil "https://github.com/microsoft/service-fabric-services-and-actors-dotnet/tree/develop/src/FabActUtil"
    click ServicesCore "https://github.com/microsoft/service-fabric-services-and-actors-dotnet/blob/develop/src/Microsoft.ServiceFabric.Services"
    click ServicesRemNative "https://github.com/microsoft/service-fabric-services-and-actors-dotnet/tree/develop/src/Microsoft.ServiceFabric.Services.Remoting/V2"
    click ServicesComm "https://github.com/microsoft/service-fabric-services-and-actors-dotnet/tree/develop/src/Microsoft.ServiceFabric.Services/Communication"
    click ServicesRemWCF "https://github.com/microsoft/service-fabric-services-and-actors-dotnet/blob/develop/src/Microsoft.ServiceFabric.Services.Wcf"
    click BuildPack "https://github.com/microsoft/service-fabric-services-and-actors-dotnet/blob/develop/build.ps1"
    click Testing "https://github.com/microsoft/service-fabric-services-and-actors-dotnet/tree/develop/test"
```
