How itoktsnhc/jobtrackerx.orleans works
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.