# parameshg/orleans-prototype architecture

> Architecture diagram of the GitHub repository parameshg/orleans-prototype, 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/parameshg/orleans-prototype
- Repository: https://github.com/parameshg/orleans-prototype

## Overview

Based on your project’s file tree and README, the system is a distributed IoT prototype that leverages Microsoft Orleans to process events from emulated IoT devices. The overall purpose is to demonstrate how Orleans’ virtual actor model can be used to build a scalable, distributed server that receives, processes, and responds to events from various IoT devices.

##### Project Type and Purpose
- This is a distributed IoT system prototype built using Microsoft Orleans. Its main goal is to handle events received from IoT devices, process these using device type–specific logic (e.g., Prime, Factorial, Mean, Variance, Standard Deviation), and send results back.
- The system spans multiple project types: a REST-based API (IoT.Api), a Windows Forms–based IoT Devices client, and a Windows Forms host (IoT.Server.Host) that runs the Orleans runtime with the core business logic encapsulated in IoT.Server and IoT.Server.Interfaces.
- It includes shared components (IoT.Shared) and uses SQL Server (with provided scripts) for persistence, clustering, and reminders.

##### Main Components
a. Client Layer (IoT.Devices)
- Represented by a Windows Forms UI that emulates IoT devices generating events.
- Details about its Redux-based local state management (Redux folders and actions/reducers).
b. API Gateway (IoT.Api)
- A REST API that acts as the entry point for device-generated events.
- Depicts the stateless API which accepts events, serves as an Orleans client, and forwards requests to the Orleans-hosted grains.
c. Orleans Cluster Host (IoT.Server.Host)
- Hosts the Orleans runtime and manages the lifecycle of grains.
- Role in activating, deactivating, and handling grain state as events are processed.
d. Business Logic/Grains (IoT.Server, IoT.Server.Interfaces, IoT.Shared)
- Core business logic encapsulated in grains (for PrimeTester, FactorialFinder, Statistics, etc.).
- IoT.Server.Interfaces exposes service interfaces for grain communication.
- IoT.Shared contains shared entities and enumerations (like the Device entity and Device status/type).
e. Persistence/Storage (IoT.Storage)
- An external Microsoft SQL Server where grain states, clustering information, and reminders are stored.
- That several SQL scripts create the necessary tables (SQLServer-Main.sql, SQLServer-Persistence.sql, etc.).

##### Relationships and Interactions
- From IoT.Devices (client) to IoT.Api: Devices send events via REST calls.
- From IoT.Api to Orleans Cluster Host (IoT.Server.Host): The API acts as an Orleans client, forwarding device events.
- Within the Orleans Cluster Host, indicate how the Orleans runtime receives events and instantiates/activates the appropriate grain (business logic in IoT.Server).

##### Architectural Patterns and Design Principles
- Use of the Virtual Actor model:
- Annotations or labels for “Grain Activation”, “Managed Grain Lifecycle”, and “State Persistence”.
- Separation between client, API, Orleans host, and persistence.
- That the system is built for scalability and resilience using Orleans’ automatic grain management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        DEV["IoT.Devices (Windows Forms Client)"]:::client
        REDUX["Redux Store, Actions, Reducers"]:::clientNote
        DEV --> REDUX
    end

    %% API Gateway
    subgraph "API Gateway"
        API["IoT.Api (REST Endpoint & Orleans Client)"]:::api
    end

    %% Orleans Cluster Host
    subgraph "Orleans Cluster Host"
        ORLEANS["IoT.Server.Host (Windows Forms - Orleans Runtime Host)"]:::orleans
        NOTE1["Grain Activation & Managed Grain Lifecycle"]:::annotation
    end

    %% Business Logic / Grains
    subgraph "Business Logic / Grains"
        GRAIN_LOGIC["IoT.Server (Grain Logic)"]:::grain
        GRAIN_INTERFACES["IoT.Server.Interfaces (Grain Interfaces)"]:::grain
        SHARED["IoT.Shared (Shared Entities & Enumerations)"]:::grain
        NOTE2["Virtual Actor Model"]:::annotation
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        SQL["SQL Server (Grain Persistence & Clustering)"]:::db
        NOTE3["State Persistence, Clustering, Reminders"]:::annotation
    end

    %% Connections
    DEV -->|"sends events"| API
    API -->|"forwards events"| ORLEANS
    ORLEANS -->|"activates"| GRAIN_LOGIC
    GRAIN_LOGIC -->|"implements interfaces"| GRAIN_INTERFACES
    GRAIN_LOGIC -->|"uses"| SHARED
    ORLEANS -->|"updates state"| SQL
    GRAIN_LOGIC -->|"persists state"| SQL
    SQL -- "returns processed results" --> API
    API -- "sends response"| DEV

    %% Annotations for Orleans Host
    ORLEANS --- NOTE1
    GRAIN_LOGIC --- NOTE2
    SQL --- NOTE3

    %% Click Events
    click DEV "https://github.com/parameshg/orleans-prototype/blob/master/IoT.Devices"
    click API "https://github.com/parameshg/orleans-prototype/blob/master/IoT.Api"
    click ORLEANS "https://github.com/parameshg/orleans-prototype/blob/master/IoT.Server.Host"
    click GRAIN_LOGIC "https://github.com/parameshg/orleans-prototype/blob/master/IoT.Server"
    click GRAIN_INTERFACES "https://github.com/parameshg/orleans-prototype/blob/master/IoT.Server.Interfaces"
    click SHARED "https://github.com/parameshg/orleans-prototype/blob/master/IoT.Shared"
    click SQL "https://github.com/parameshg/orleans-prototype/blob/master/IoT.Storage"

    %% Styles
    classDef client fill:#f4a261,stroke:#e76f51,stroke-width:2px;
    classDef clientNote fill:#f9c74f,stroke:#f9844a,stroke-width:1px,stroke-dasharray: 5, 5;
    classDef api fill:#2a9d8f,stroke:#264653,stroke-width:2px;
    classDef orleans fill:#457b9d,stroke:#1d3557,stroke-width:2px;
    classDef grain fill:#a8dadc,stroke:#457b9d,stroke-width:2px;
    classDef db fill:#e9c46a,stroke:#f4a261,stroke-width:2px,stroke-dasharray: 3, 3;
    classDef annotation fill:#ddd,stroke:#555,stroke-width:1px,stroke-dasharray: 2, 2;
```
