ThunderPropagator.BuildingBlocks.Modules 1.0.1-beta.26

ThunderPropagator BuildingBlocks (Project ARC)

ThunderPropagator BuildingBlocks (Project ARC) is a comprehensive .NET library providing production-ready, reusable components for building high-performance, cloud-native applications. Targets .NET 8.0, 9.0, and 10.0 with multi-platform support (AnyCPU, x86, x64, ARM64).

📚 Documentation

Main Documentation Hub: docs/README.md

Documentation Catalog

Application Layer (Core Building Blocks)

Infrastructure Layer (System-Level Components)

Total: 100+ types, 92 files, 25+ diagrams created

Last generated: December 28, 2025

📦 NuGet Installation (GitHub Packages)

ThunderPropagator packages are hosted on GitHub Packages: https://nuget.pkg.github.com/KiarashMinoo/index.json

Configure NuGet Source

Option 1: nuget.config (recommended)

<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="github" value="https://nuget.pkg.github.com/KiarashMinoo/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="github">
      <package pattern="ThunderPropagator.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
  <packageSourceCredentials>
    <github>
      <add key="Username" value="YOUR_GITHUB_USERNAME" />
      <add key="ClearTextPassword" value="YOUR_GITHUB_PAT" />
    </github>
  </packageSourceCredentials>
</configuration>

Option 2: CLI

dotnet nuget add source https://nuget.pkg.github.com/KiarashMinoo/index.json \
  --name github \
  --username YOUR_GITHUB_USERNAME \
  --password YOUR_GITHUB_PAT \
  --store-password-in-clear-text

Install Packages

# Core application building blocks
dotnet add package ThunderPropagator.BuildingBlocks.Application

# Infrastructure components
dotnet add package ThunderPropagator.BuildingBlocks.Infrastructure

🎯 Quick Start

FeederMessage Pattern

using ThunderPropagator.BuildingBlocks.Application;

public class OrderMessage : FeederMessage
{
    public Guid OrderId
    {
        get => GetValueOrDefault(Guid.NewGuid());
        set => SetValue(value);
    }
    
    public decimal Amount
    {
        get => GetValueOrDefault(0m);
        set => SetValue(value);
    }
}

var order = new OrderMessage
{
    OrderId = Guid.NewGuid(),
    Amount = 99.99m,
    CorrelationId = "req-12345"
};

System Resource Monitoring

using ThunderPropagator.BuildingBlocks.Infrastructure.SystemResourceMonitor;

services.AddSystemResourceMonitor(options =>
{
    options.EnableCpuMetrics = true;
    options.EnableMemoryMetrics = true;
    options.EnableDiskHealth = true;
    options.DefaultSamplingWindowMs = 500;
});

// Inject and use
public class MonitoringService
{
    private readonly ISystemResourceMonitor _monitor;
    
    public MonitoringService(ISystemResourceMonitor monitor)
    {
        _monitor = monitor;
    }
    
    public async Task<SystemResourceMonitorMetrics> GetMetricsAsync()
    {
        return await _monitor.GetMetricsAsync();
    }
}

Serialization Helpers

using ThunderPropagator.BuildingBlocks.Application.Helpers;

// JSON
var json = myObject.ToJson();
var obj = json.FromJson<MyType>();

// YAML
var yaml = myObject.ToYaml();

// ProtoBuf
var bytes = myObject.ToProtoBufBytes();

// MessagePack
var base64 = myObject.ToMessagePackBase64();

🛠 Build & Test

# Restore dependencies
dotnet restore

# Build (Release)
dotnet build -c Release

# Run tests
dotnet test -c Release

# Package
dotnet pack -c Release -o artifacts/pkg

Multi-Platform Builds:

• Platforms: AnyCPU, x86, x64, ARM64
• Frameworks: net8.0, net9.0, net10.0

📄 Available Packages

📖 Key Features

Application Layer

• FeederMessage: Dictionary-based message abstraction with correlation ID
• ServiceConfiguration: Strongly-typed configuration with change notifications
• Telemetry: OpenTelemetry integration (Activities, Counters, Histograms)
• Helpers: Comprehensive serialization (JSON, YAML, ProtoBuf, MessagePack, NetJSON, Newtonsoft.Json)
• Collections: LinkedArray, BindingDictionary, GenericOrderedDictionary
• Ciphering: AES/RSA encryption, password generation
• Objects: DisposableObject, EquatableObject, NotifiableObject base classes

Infrastructure Layer

• SystemResourceMonitor: Cross-platform monitoring (CPU, Memory, Disk, GPU, Battery)
• Platform Providers: Windows/Linux/macOS with graceful degradation
• SMART Disk Health: Disk health monitoring via platform-specific tools
• GPU Metrics: nvidia-smi/rocm-smi integration
• Battery Status: Power management metrics
• No External Packages: Uses .NET BCL and CLI tools only

🏗 Architecture

The solution follows a strict two-layer architecture:

1. Application Layer (ThunderPropagator.BuildingBlocks.Application)

   • Core building blocks with NO infrastructure dependencies
   • Helpers, serialization, collections, base classes
   • Verified by Tests/ArchTests/ArchitectureTests.cs

2. Infrastructure Layer (ThunderPropagator.BuildingBlocks.Infrastructure)

   • System-level components (monitoring, health checks)
   • Depends on Application layer
   • Platform-specific providers with graceful degradation

Critical Rule: Application layer MUST NEVER depend on Infrastructure layer.

🧪 Testing

Run All Tests

dotnet test -c Release

Architecture Tests

Architecture constraints are enforced by NetArchTest.Rules in Tests/ArchTests/:

• Application layer has no Infrastructure dependencies
• Naming conventions
• Layer boundaries

Unit Tests

Comprehensive unit tests with xUnit and NSubstitute in Tests/ThunderPropagator.UnitTests/:

• FeederMessage, ServiceConfiguration tests
• Helper method tests
• Collection tests
• SystemResourceMonitor tests

Benchmarks

BenchmarkDotNet benchmarks for performance-critical code:

• CollectionHelperBenchmark.cs
• SizeBenchmark.cs

🚀 CI/CD Workflows

• develop branch → develop-beta-ci.yml → Increments beta version
• release/ branch → develop-release-ci.yml → Creates GitHub release, strips beta suffix
• GitHub Packages feed: https://nuget.pkg.github.com/KiarashMinoo/index.json

📝 Contributing

1. Follow the existing code conventions (see .github/copilot-instructions.md)
2. Add XML documentation for all public APIs
3. Include unit tests for new features
4. Update relevant documentation in /docs
5. Ensure architecture tests pass

📜 License

See LICENSE for details.