# dotnet/orleans architecture

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

- Interactive diagram: https://gitdiagram.com/dotnet/orleans
- Repository: https://github.com/dotnet/orleans

## Overview

##### Core Components (Main Layer)

a. Silo Layer (Central Component)
- Multiple silos forming a cluster
- Runtime services within each silo

b. Grain Layer
- Grains inside silos
- Grain components: Identity, State, Behavior
- Grain lifecycle management

c. Client Layer
- Client applications connecting to the cluster
- Client library components

##### Key Subsystems (Secondary Layer)

a. Membership & Clustering
- Membership table
- Cluster management components
- Silo-to-silo communication

b. Storage Providers
- Persistence systems
- State management
- Different storage options (Azure, AWS, ADO.NET)

c. Streaming System
- Stream providers
- Pub/sub infrastructure
- Queue integration

##### Supporting Features (Tertiary Layer)

a. Transaction System
- Transaction manager
- ACID guarantees
- Distributed transaction coordination

b. Reminders & Timers
- Reminder service
- Timer management

c. Placement & Load Balancing
- Placement strategies
- Load balancer
- Directory service

##### Cross-Cutting Concerns

a. Security
- Authentication
- Authorization
- Transport security

b. Monitoring & Diagnostics
- Telemetry
- Logging
- Health monitoring

Use the following visual elements:

- Blue: Core runtime components
- Green: Grain-related components
- Orange: Client components
- Purple: Storage and persistence
- Yellow: Streaming and messaging

##### Labels
- Clear component names
- Interface definitions
- Protocol indicators
- Version information

##### Grouping
- Cluster boundary
- Silo boundaries
- Subsystem boundaries

Specific aspects from the codebase:

##### Relationship between
- src/Orleans.Runtime (Silo implementation)
- src/Orleans.Core (Core functionality)
- src/Orleans.Streaming (Streaming infrastructure)
- src/Orleans.Transactions (Transaction system)

##### Integration points
- Azure components (src/Azure)
- AWS components (src/AWS)
- ADO.NET providers (src/AdoNet)

##### Extension points
- Custom storage providers
- Stream providers
- Grain interfaces

- Distributed nature
- Elasticity and fault tolerance
- Virtual actor model
- State management
- Programming model simplicity

Remember to maintain a balance between detail and clarity, focusing on the architectural aspects while avoiding implementation-specific details.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Cluster["Orleans Cluster"]
        subgraph SiloLayer["Silo Layer"]
            Silo1["Silo Instance 1"]:::silo
            Silo2["Silo Instance 2"]:::silo
            Silo3["Silo Instance 3"]:::silo
        end

        subgraph GrainLayer["Grain Layer"]
            Grains["Grain Instances"]:::grain
            GrainDir["Grain Directory"]:::core
            Reminders["Reminders Service"]:::core
            EventSourcing["Event Sourcing"]:::core
        end

        subgraph RuntimeServices["Runtime Services"]
            Membership["Membership & Clustering"]:::core
            Placement["Placement & Load Balancing"]:::core
            Transactions["Transaction System"]:::core
            Security["Security Services"]:::security
            Monitoring["Monitoring & Diagnostics"]:::monitoring
        end

        subgraph Storage["Storage Providers"]
            AzureStorage["Azure Storage"]:::azure
            DynamoDB["AWS DynamoDB"]:::aws
            AdoNet["ADO.NET Storage"]:::storage
        end

        subgraph Streaming["Streaming System"]
            EventHubs["Azure Event Hubs"]:::azure
            SQS["AWS SQS"]:::aws
            AzureQueue["Azure Storage Queue"]:::azure
        end

        subgraph Clustering["Clustering Providers"]
            AzureCluster["Azure Clustering"]:::azure
            ConsulCluster["Consul"]:::cluster
            ZooKeeper["ZooKeeper"]:::cluster
            DynamoCluster["DynamoDB Clustering"]:::aws
        end
    end

    ClientApps["Client Applications"]:::client
    CodeGen["Code Generator"]:::tool
    TestHost["Testing Infrastructure"]:::testing

    ClientApps --> SiloLayer
    SiloLayer --> GrainLayer
    GrainLayer --> Storage
    GrainLayer --> Streaming
    RuntimeServices --> SiloLayer
    Clustering --> Membership
    CodeGen --> GrainLayer
    TestHost --> Cluster

    %% Component Mappings
    click Silo1 "https://github.com/dotnet/orleans/blob/main/src/Orleans.Runtime/Silo/Silo.cs"
    click GrainDir "https://github.com/dotnet/orleans/tree/main/src/Orleans.Core/GrainDirectory"
    click Reminders "https://github.com/dotnet/orleans/blob/main/src/Orleans.Reminders"
    click EventSourcing "https://github.com/dotnet/orleans/blob/main/src/Orleans.EventSourcing"
    click Transactions "https://github.com/dotnet/orleans/blob/main/src/Orleans.Transactions"
    click Security "https://github.com/dotnet/orleans/blob/main/src/Orleans.Connections.Security"
    click Monitoring "https://github.com/dotnet/orleans/tree/main/src/Orleans.Core/Diagnostics"
    click AzureStorage "https://github.com/dotnet/orleans/blob/main/src/Azure/Orleans.Persistence.AzureStorage"
    click DynamoDB "https://github.com/dotnet/orleans/blob/main/src/AWS/Orleans.Persistence.DynamoDB"
    click AdoNet "https://github.com/dotnet/orleans/blob/main/src/AdoNet/Orleans.Persistence.AdoNet"
    click EventHubs "https://github.com/dotnet/orleans/blob/main/src/Azure/Orleans.Streaming.EventHubs"
    click SQS "https://github.com/dotnet/orleans/blob/main/src/AWS/Orleans.Streaming.SQS"
    click AzureQueue "https://github.com/dotnet/orleans/blob/main/src/Azure/Orleans.Streaming.AzureStorage"
    click AzureCluster "https://github.com/dotnet/orleans/blob/main/src/Azure/Orleans.Clustering.AzureStorage"
    click ConsulCluster "https://github.com/dotnet/orleans/blob/main/src/Orleans.Clustering.Consul"
    click ZooKeeper "https://github.com/dotnet/orleans/blob/main/src/Orleans.Clustering.ZooKeeper"
    click DynamoCluster "https://github.com/dotnet/orleans/blob/main/src/AWS/Orleans.Clustering.DynamoDB"
    click CodeGen "https://github.com/dotnet/orleans/blob/main/src/Orleans.CodeGenerator"
    click TestHost "https://github.com/dotnet/orleans/blob/main/src/Orleans.TestingHost"

    %% Styling
    classDef silo fill:#2196F3,stroke:#1565C0,color:white
    classDef grain fill:#4CAF50,stroke:#388E3C,color:white
    classDef core fill:#3F51B5,stroke:#303F9F,color:white
    classDef azure fill:#00BCD4,stroke:#0097A7,color:white
    classDef aws fill:#FF9800,stroke:#F57C00,color:white
    classDef storage fill:#9C27B0,stroke:#7B1FA2,color:white
    classDef cluster fill:#FF5722,stroke:#E64A19,color:white
    classDef security fill:#F44336,stroke:#D32F2F,color:white
    classDef monitoring fill:#795548,stroke:#5D4037,color:white
    classDef client fill:#009688,stroke:#00796B,color:white
    classDef tool fill:#607D8B,stroke:#455A64,color:white
    classDef testing fill:#9E9E9E,stroke:#616161,color:white
```
