# itoktsnhc/jobtrackerx.orleans architecture

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

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

## Overview

##### Project Type and Purpose
- JobTrackerX.Orleans is a distributed, full-stack task status tracking system built on Microsoft Orleans (Virtual Actor) framework.
- It provides:
- A backend Orleans cluster (Silos) co-hosted with an ASP .NET Core Web API and Blazor Server-Side UI.
- A C# Client SDK (JobTrackerX.Client) for programmatic access.
- A sample console trigger (JobTrackerX.SampleTrigger) and a test suite.

##### File Structure Analysis
- Top-level solution file (.sln) with multiple class-library projects and one WebApi project.
- Projects:
- JobTrackerX.Grains – grain implementations (JobGrain, JobIdGrain, AggregateJobIndexGrain, CounterGrains, etc.), including in-memory variants.
- JobTrackerX.GrainInterfaces – grain interface definitions.
- JobTrackerX.Entities – data transfer objects, state wrappers, constants.
- JobTrackerX.SharedLibs – shared DTOs/enums/exceptions used by SDK and WebApi.
- JobTrackerX.Client – C# SDK exposing IJobTrackerClient and Orleans client context.
- JobTrackerX.WebApi – ASP .NET Core co-hosted with Orleans: controllers, Razor pages (Blazor UI), background services, ActionHandler, and configuration.
- JobTrackerX.SampleTrigger – console app acting as an Orleans client.
- JobTrackerX.Test – automated tests.
- Configuration & deployment: Dockerfiles in WebApi and SampleTrigger; GitHub Actions workflows for NuGet and DockerHub.

##### Key Architecture Insights from README
- Co-hosting ASP .NET Core and Orleans Generic Host in the same process (one host per Silo).
- Orleans Cluster uses Azure Storage Table for both Grain state persistence and clustering membership.
- Root job indices stored in Azure Table, then aggregated and compressed into Azure Blob via AggregateJobIndexGrain.
- Azure Service Bus Queue used for scheduled state checks and external callbacks.
- Two-level counter via AggregateCounterGrain (StatelessWorker) and CounterGrain to overcome single-object IOPS limits.

##### Main Components
a. External Clients
- C# SDK clients (JobTrackerX.Client, SampleTrigger)
- Web browser (Blazor Server UI)
b. Reverse Proxy / Load Balancer (optional)
c. ASP .NET Core + Orleans Generic Host (per Silo node)
- Web API controllers
- Background services (ActionHandlerService, StateChecker)
- Blazor Server-Side pages & layouts
- Orleans Silo runtime hosting grains
d. Orleans Cluster
- Multiple Silo nodes (Silo1, Silo2, …) communicating via silo & gateway ports
- Grain activations: JobGrain, JobIdGrain, AggregateJobIndexGrain, CounterGrains, etc.
e. External Stateful Services
- Azure Storage Table – Grain state store & clustering membership, RootJob index table
- Azure Blob Storage – Aggregated job indices
- Azure Service Bus Queue – Scheduled messages for state checks and external callbacks

##### Relationships and Data Flows
- Clients call the ASP .NET Core Web API (or connect directly via Orleans client SDK to gateway port).
- Web API controllers invoke Orleans grains through the Orleans client API.
- Grain methods manipulate in-memory state and persist to Azure Table.
- Child-to-parent grain state changes “bubble up” via grain calls.
- AggregateJobIndexGrain periodically merges table indices into Blob storage.
- On state changes or scheduled checks, grains send messages to Service Bus.
- ASP .NET Core background service listens on Service Bus and invokes external HTTP/email callbacks.

##### Architectural Patterns & Design Principles
- Virtual Actor (Orleans Grain) model for single-threaded, per-ID state management.
- Co-hosting Generic Host to simplify deployment (one process runs both API & silo).
- Sharding of counters (two-level grain structure) for high-throughput counters.
- Time-based aggregation for indexing root jobs (hourly table → blob).
- Event-driven callbacks via Service Bus.

##### Detailed Callouts (optional zoom-in)
- Grain hierarchy: JobIdGrain → JobGrain → AggregateJobIndexGrain → CounterGrains.
- Data flow for job creation, state update, index aggregation, state check scheduling, and callback dispatch.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients Layer
    subgraph "External Clients" 
        direction TB
        SDK["C# Client SDK\n(JobTrackerX.Client)"]:::frontend
        Sample["Sample Trigger\n(JobTrackerX.SampleTrigger)"]:::frontend
        Browser["Web Browser\n(Blazor UI)"]:::frontend
    end

    %% Reverse Proxy
    Proxy["Reverse Proxy / Load Balancer"]:::external

    %% Orleans Cluster
    subgraph "Orleans Cluster"
        direction TB
        subgraph "Silo 1\n(silo port: 11111\ngateway port: 30000)"
            direction TB
            Host1["Generic Host\n(API + Orleans Runtime)"]:::backend
            subgraph "Web API Controllers & Blazor UI"
                Controllers1["Controllers & Pages"]:::backend
            end
            subgraph "Background Services"
                BG1["StateChecker\nActionHandlerService"]:::service
            end
            subgraph "Orleans Grains"
                Grains1["Grain Implementations"]:::backend
            end
        end
        subgraph "Silo 2\n(silo port: 11112\ngateway port: 30001)"
            direction TB
            Host2["Generic Host\n(API + Orleans Runtime)"]:::backend
            subgraph "Web API Controllers & Blazor UI"
                Controllers2["Controllers & Pages"]:::backend
            end
            subgraph "Background Services"
                BG2["StateChecker\nActionHandlerService"]:::service
            end
            subgraph "Orleans Grains"
                Grains2["Grain Implementations"]:::backend
            end
        end
    end

    %% External Storages
    StorageTable["Azure Storage Table"]:::storage
    BlobStorage["Azure Blob Storage"]:::storage
    ServiceBus["Azure Service Bus Queue"]:::storage

    %% Connections
    SDK -->|Orleans Gateway| Proxy
    Sample -->|Orleans Gateway| Proxy
    Browser -->|HTTPS/API Calls| Proxy
    Proxy -->|API Requests| Host1
    Proxy -->|API Requests| Host2

    Host1 -->|persist/read| StorageTable
    Host2 -->|persist/read| StorageTable

    Grains1 -->|aggregate indices| BlobStorage
    Grains2 -->|aggregate indices| BlobStorage

    Grains1 -->|enqueue messages| ServiceBus
    Grains2 -->|enqueue messages| ServiceBus

    ServiceBus -->|triggers| BG1
    ServiceBus -->|triggers| BG2

    BG1 -->|external callbacks| Browser
    BG2 -->|external callbacks| Browser

    %% Click Events
    click SDK "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.Client/JobTrackerX.Client.csproj"
    click Sample "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.SampleTrigger/Program.cs"
    click Sample "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.SampleTrigger/JobTrackerX.SampleTrigger.csproj"
    click Sample "https://github.com/itoktsnhc/jobtrackerx.orleans/tree/master/JobTrackerX.SampleTrigger/Dockerfile"
    click Controllers1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.WebApi/Controllers/JobTrackerController.cs"
    click Controllers1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.WebApi/Controllers/AttachmentController.cs"
    click Controllers1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.WebApi/Controllers/BufferManagerController.cs"
    click Controllers1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.WebApi/Controllers/ConfigController.cs"
    click Controllers1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.WebApi/Controllers/QueryIndexController.cs"
    click BG1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.WebApi/Services/Background/StateChecker.cs"
    click BG1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.WebApi/Services/Background/ActionHandlerService.cs"
    click BG1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.WebApi/Services/ActionHandler/ActionHandlerPool.cs"
    click Host1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.WebApi/Program.cs"
    click Host1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.WebApi/Startup.cs"
    click Host1 "https://github.com/itoktsnhc/jobtrackerx.orleans/tree/master/JobTrackerX.WebApi/Dockerfile"
    click Grains1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.Grains/JobGrain.cs"
    click Grains1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.Grains/JobIdGrain.cs"
    click Grains1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.Grains/AggregateJobIndexGrain.cs"
    click Grains1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.Grains/CounterGrain.cs"
    click Grains1 "https://github.com/itoktsnhc/jobtrackerx.orleans/blob/master/JobTrackerX.Grains/AggregateCounterGrain.cs"

    %% Styles
    classDef frontend fill:#ccffcc,stroke:#009900,color:#004400
    classDef backend fill:#cce5ff,stroke:#004080,color:#002050
    classDef service fill:#ffe5cc,stroke:#cc8400,color:#804000
    classDef external fill:#e0e0e0,stroke:#888888,color:#444444
    classDef storage fill:#f2f2f2,stroke:#666666,color:#333333,stroke-dasharray: 5 5
```
