BR.Workflow.Contracts 1.0.24

BR.Workflow.Contracts

A comprehensive .NET 8 library containing Temporal workflow and activity contracts for distributed workflow processing systems. Built with Clean Architecture principles and clear separation of concerns across service domains.

🎯 What This Package Provides

BR.Workflow.Contracts is the foundation for building distributed, scalable workflow systems using Temporal.io and .NET 8. It provides:

• 🏗️ Workflow Contracts - Define workflow orchestration patterns
• ⚡ Activity Contracts - Define individual processing steps
• 📊 Data Models - Immutable, validated data contracts
• 🔧 Utility Extensions - Helper methods for common operations
• 🎨 Clean Architecture - Well-organized, maintainable code structure

🏗️ Architecture Overview

This package implements Clean Architecture with clear separation by service domains:

Service Domains

Architecture Principles

• ✅ Separation of Concerns - Clear boundaries between domains
• ✅ Dependency Inversion - Interfaces depend on abstractions
• ✅ Single Responsibility - Each contract has one purpose
• ✅ Open/Closed - Extensible without modification
• ✅ Interface Segregation - Clients only depend on what they use

✨ Key Features

Core Features

• 🚀 .NET 8 Compatible - Latest language features and performance improvements
• 🔒 Nullable Reference Types - Full nullable annotations for better code safety
• 📝 Data Annotations - Comprehensive validation attributes
• 📚 XML Documentation - Complete API documentation
• 🧵 Immutable Records - Thread-safe, immutable data contracts
• 🔧 Extension Methods - Utility extensions for common operations

Temporal Integration

• ⏰ Native Temporal Support - Built for Temporal.io workflows
• 🔄 Workflow Orchestration - Define complex workflow patterns
• ⚡ Activity Contracts - Define individual processing steps
• 🎯 Task Queue Management - Organized by service domain

Production Ready

• 🧪 Comprehensive Testing - Full test coverage
• 📊 Performance Optimized - Minimal allocations and async patterns
• 🔒 Security Focused - Input validation and secure defaults
• 📈 Monitoring Ready - Built-in audit and error tracking

📦 Installation

NuGet Package

dotnet add package BR.Workflow.Contracts

Package Manager Console

Install-Package BR.Workflow.Contracts

Direct Reference

<PackageReference Include="BR.Workflow.Contracts" Version="1.0.17" />

🏛️ Project Structure

BR.Workflow.Contracts/
├── 📁 Workflows/                    # Workflow orchestration contracts
│   ├── IStartRealEstateWorkflow.cs  # Main workflow interface
│   └── Models/
│       └── RealEstateWorkflowOutput.cs
│
├── 📁 Activities/                   # Activity contracts by service domain
│   ├── 🏠 REI/                     # Real Estate Ingestor (3 activities)
│   │   ├── IValidateEventActivity.cs
│   │   ├── IDownloadBlobActivity.cs
│   │   └── IUpdateOrderStatusInBlobActivity.cs
│   │
│   ├── ⚙️ REP/                     # Real Estate Processor (9 activities)
│   │   ├── IValidateSchemaTemplateActivity.cs
│   │   ├── IDetermineActionTypeActivity.cs
│   │   ├── ICreateOrderActivity.cs
│   │   ├── IUpdateOrderActivity.cs
│   │   ├── IApproveOrderActivity.cs
│   │   ├── IRejectOrderActivity.cs
│   │   ├── INotifyClientActivity.cs
│   │   ├── IUpdateDbActivity.cs
│   │   └── ICallApiGatewayActivity.cs
│   │
│   └── 🔄 PT/                      # Payload Transformer (1 activity)
│       └── ITransformPayloadActivity.cs
│
├── 📁 Models/                       # Data models organized by domain
│   ├── 🌐 Common/                   # Shared models across all services
│   │   ├── AuditInfo.cs            # Workflow execution audit
│   │   ├── ErrorInfo.cs            # Error details and tracking
│   │   ├── ValidationError.cs      # Validation failure details
│   │   ├── ValidationResult.cs     # Validation operation results
│   │   ├── StatusUpdate.cs         # Status change notifications
│   │   ├── ApiGatewayResponse.cs   # External API responses
│   │   ├── BlobMetadata.cs         # Blob storage metadata
│   │   ├── DownloadInfo.cs         # Download operation details
│   │   └── DuplicateCheck.cs       # Duplicate detection results
│   │
│   ├── 📨 Kafka/                   # Kafka payload and workflow input
│   │   ├── RealEstateWorkflowInput.cs  # Main workflow input
│   │   ├── EventInfo.cs            # Event metadata and correlation
│   │   ├── ClientInfo.cs           # Client identification
│   │   ├── BlobInfo.cs             # Blob storage information
│   │   ├── DeadLetterEvent.cs      # DLQ event handling
│   │   └── DlqDetails.cs           # DLQ failure details
│   │
│   ├── 🏠 REI/                     # Real Estate Ingestor models
│   │   ├── ValidateEventInput.cs   # Event validation input
│   │   ├── ValidateEventOutput.cs  # Event validation results
│   │   ├── DownloadBlobInput.cs    # Blob download parameters
│   │   ├── DownloadBlobOutput.cs   # Blob download results
│   │   ├── UpdateOrderStatusInput.cs   # Status update input
│   │   └── UpdateOrderStatusOutput.cs  # Status update results
│   │
│   ├── ⚙️ REP/                     # Real Estate Processor models
│   │   ├── ValidateSchemaInput.cs  # Schema validation input
│   │   ├── ValidateSchemaOutput.cs # Schema validation results
│   │   ├── DetermineActionInput.cs # Action determination input
│   │   ├── DetermineActionOutput.cs # Action determination results
│   │   ├── CreateOrderInput.cs     # Order creation input
│   │   ├── CreateOrderOutput.cs    # Order creation results
│   │   ├── UpdateOrderInput.cs     # Order update input
│   │   ├── UpdateOrderOutput.cs    # Order update results
│   │   ├── ApproveOrderInput.cs    # Order approval input
│   │   ├── ApproveOrderOutput.cs   # Order approval results
│   │   ├── RejectOrderInput.cs     # Order rejection input
│   │   ├── RejectOrderOutput.cs    # Order rejection results
│   │   ├── NotifyClientInput.cs    # Client notification input
│   │   ├── NotifyClientOutput.cs   # Client notification results
│   │   ├── UpdateDbInput.cs        # Database update input
│   │   ├── UpdateDbOutput.cs       # Database update results
│   │   ├── CallApiGatewayInput.cs  # API Gateway call input
│   │   └── CallApiGatewayOutput.cs # API Gateway call results
│   │
│   └── 🔄 PT/                      # Payload Transformer models
│       ├── TransformPayloadInput.cs # Transformation input
│       ├── TransformPayloadOutput.cs # Transformation results
│       └── TransformationRules.cs   # Transformation configuration
│
├── 📁 Enums/                       # Type-safe enumerations
│   ├── ActionType.cs               # Order processing actions
│   ├── BrightRiverStatus.cs        # Bright River specific statuses
│   ├── DeliveryStatus.cs           # Delivery operation statuses
│   ├── HttpMethod.cs               # HTTP method constants
│   ├── NotificationType.cs         # Notification type definitions
│   ├── OrderStatus.cs              # Order lifecycle statuses
│   └── ValidationSeverity.cs       # Validation error severity levels
│
├── 📁 Extensions/                  # Utility extension methods
│   ├── TemporalExtensions.cs       # Workflow result helpers
│   ├── ContractExtensions.cs       # Contract utility methods
│   └── ValidationExtensions.cs     # Validation helper methods
│
├── 📁 Constants/                   # Configuration constants
│   ├── ActivityNames.cs            # Activity naming constants
│   ├── ConfigurationKeys.cs        # Configuration key constants
│   ├── TaskQueues.cs               # Task queue names
│   ├── WorkflowNames.cs            # Workflow naming constants
│   └── WorkflowTypes.cs            # Workflow type definitions
│
└── 📁 Scripts/                     # Build and deployment automation
    ├── build-and-publish.ps1       # PowerShell build & publish script
    ├── build-and-publish.cmd       # Windows batch build & publish script
    ├── build.ps1                   # Comprehensive build script
    ├── build.cmd                   # Windows build script
    └── publish.ps1                 # NuGet publishing script

🚀 Quick Start Guide

1. Basic Workflow Implementation

using BR.Workflow.Contracts.Workflows;
using BR.Workflow.Contracts.Models.Kafka;
using BR.Workflow.Contracts.Workflows.Models;

public class StartRealEstateWorkflow : IStartRealEstateWorkflow
{
    public async Task<RealEstateWorkflowOutput> ExecuteAsync(RealEstateWorkflowInput input)
    {
        try
        {
            // Your workflow logic here
            return new RealEstateWorkflowOutput
            {
                WorkflowId = Guid.NewGuid(),
                Status = "Completed",
                ClientId = input.ClientInfo.Id,
                OrderId = Guid.NewGuid(),
                ActionType = ActionType.Create,
                ApiGatewayResponse = new ApiGatewayResponse
                {
                    Success = true,
                    StatusCode = 200,
                    Message = "Order created successfully"
                },
                AuditInfo = new AuditInfo
                {
                    CompletedAt = DateTime.UtcNow,
                    ErrorInfo = Array.Empty<ErrorInfo>()
                }
            };
        }
        catch (Exception ex)
        {
            return new RealEstateWorkflowOutput
            {
                WorkflowId = Guid.NewGuid(),
                Status = "Failed",
                ClientId = input.ClientInfo.Id,
                OrderId = Guid.Empty,
                ActionType = ActionType.Create,
                ApiGatewayResponse = new ApiGatewayResponse
                {
                    Success = false,
                    StatusCode = 500,
                    Message = ex.Message
                },
                AuditInfo = new AuditInfo
                {
                    CompletedAt = DateTime.UtcNow,
                    ErrorInfo = new[] { new ErrorInfo { Message = ex.Message, Severity = ValidationSeverity.Error } }
                }
            };
        }
    }
}

2. Activity Implementation

using BR.Workflow.Contracts.Activities.REI;
using BR.Workflow.Contracts.Models.REI;
using BR.Workflow.Contracts.Models.Common;

public class ValidateEventActivity : IValidateEventActivity
{
    public async Task<ValidateEventOutput> ValidateAsync(ValidateEventInput input)
    {
        var validationErrors = new List<ValidationError>();

        // Validate correlation ID
        if (string.IsNullOrEmpty(input.CorrelationId))
        {
            validationErrors.Add(new ValidationError
            {
                Field = nameof(input.CorrelationId),
                Message = "Correlation ID is required",
                Severity = ValidationSeverity.Error
            });
        }

        // Validate client ID
        if (input.ClientId == Guid.Empty)
        {
            validationErrors.Add(new ValidationError
            {
                Field = nameof(input.ClientId),
                Message = "Valid Client ID is required",
                Severity = ValidationSeverity.Error
            });
        }

        // Check for duplicates
        var duplicateCheck = await CheckForDuplicatesAsync(input.CorrelationId, input.ClientId);

        return new ValidateEventOutput
        {
            CanProceed = validationErrors.Count == 0,
            DuplicateCheck = duplicateCheck,
            ValidationErrors = validationErrors.ToArray()
        };
    }

    private async Task<DuplicateCheck> CheckForDuplicatesAsync(string correlationId, Guid clientId)
    {
        // Your duplicate checking logic here
        return new DuplicateCheck
        {
            RecentlyDownloaded = false,
            DownloadCount = 0
        };
    }
}

3. Using Extension Methods

using BR.Workflow.Contracts.Extensions;

// Create workflow results easily
var successResult = TemporalExtensions.CreateSuccessResult(
    workflowId: Guid.NewGuid(),
    status: "Completed",
    clientId: clientId,
    orderId: orderId,
    actionType: ActionType.Create
);

// Validate contract inputs
if (!input.IsValid())
{
    var errors = input.GetValidationErrors();
    foreach (var error in errors)
    {
        Console.WriteLine($"Validation Error: {error.Field} - {error.Message}");
    }
}

// Create error results
var errorResult = TemporalExtensions.CreateErrorResult(
    workflowId: Guid.NewGuid(),
    status: "Failed",
    clientId: clientId,
    orderId: orderId,
    actionType: ActionType.Create,
    errorMessage: "Processing failed"
);

🔧 Service Domain Deep Dive

🏠 REI (Real Estate Ingestor)

Purpose: Handle incoming events and manage blob storage operations

Key Activities:

• IValidateEventActivity - Validate incoming events and check for duplicates
• IDownloadBlobActivity - Download blob content from Azure Storage
• IUpdateOrderStatusInBlobActivity - Update order status in blob storage

Use Cases:

• Event deduplication and validation
• Blob content retrieval for processing
• Status tracking in blob storage

⚙️ REP (Real Estate Processor)

Purpose: Core business logic for order processing and client communication

Key Activities:

• IValidateSchemaTemplateActivity - Validate data against business schemas
• IDetermineActionTypeActivity - Determine processing action type
• ICreateOrderActivity - Create new orders
• IUpdateOrderActivity - Update existing orders
• IApproveOrderActivity - Approve orders
• IRejectOrderActivity - Reject orders
• INotifyClientActivity - Notify clients of status changes
• IUpdateDbActivity - Update processing status in database
• ICallApiGatewayActivity - Communicate with external services

Use Cases:

• Order lifecycle management
• Business rule validation
• Client communication
• External service integration

🔄 PT (Property Transformer)

Purpose: Transform data between different service formats

Key Activities:

• ITransformPayloadActivity - Transform data between formats

Use Cases:

• Data format conversion
• Schema mapping
• External service compatibility

📨 Kafka Integration

The library provides dual-purpose models that serve both Kafka messaging and workflow processing:

Kafka Payload Models

Key Features

• JSON Serialization - JsonPropertyName attributes for camelCase JSON
• Kafka Compatibility - Optimized for message serialization/deserialization
• Workflow Integration - Seamless integration with Temporal workflows
• Type Safety - Full nullable reference type support
• Validation - Comprehensive data validation attributes

Usage Pattern

// Kafka message processing
var kafkaPayload = JsonSerializer.Deserialize<RealEstateWorkflowInput>(kafkaMessage);

// Validate the payload
if (!kafkaPayload.IsValid())
{
    var errors = kafkaPayload.GetValidationErrors();
    // Handle validation errors...
}

// Workflow execution
var result = await workflow.ExecuteAsync(kafkaPayload);

📋 Complete Contract Reference

Workflows

Activities (13 Total)

REI Activities (3)

REP Activities (9)

PT Activities (1)

Enums

🎯 Clean Architecture Benefits

Design Principles

• Separation of Concerns - Clear boundaries between service domains
• Dependency Inversion - Interfaces depend on abstractions, not concretions
• Single Responsibility - Each contract has a single, well-defined purpose
• Open/Closed Principle - Easy to extend without modifying existing contracts
• Interface Segregation - Clients only depend on interfaces they use

Implementation Benefits

• Maintainability - Clear structure makes code easy to understand and modify
• Testability - Interfaces make unit testing straightforward
• Extensibility - New features can be added without breaking existing code
• Reusability - Contracts can be used across different implementations
• Documentation - Clear interfaces serve as living documentation

🚀 Production Readiness

The project follows all specified C# .NET development guidelines:

Code Quality

• ✅ PascalCase naming conventions for all public members
• ✅ Async/await patterns for I/O operations
• ✅ Comprehensive error handling with custom exceptions
• ✅ Dependency injection principles for loose coupling
• ✅ Modern C# features (records, pattern matching, nullable references)

Performance & Security

• ✅ Thread-safe immutable data contracts using records
• ✅ Minimal allocations and optimized async patterns
• ✅ Input validation and secure defaults
• ✅ Comprehensive XML documentation for all public APIs
• ✅ Nullable reference types for better type safety

Testing & Monitoring

• ✅ Full test coverage for all contracts and extensions
• ✅ Built-in audit tracking for workflow execution
• ✅ Error tracking with detailed error information
• ✅ Validation results for debugging and monitoring

🔧 Build and Deployment

Single Command Build & Publish

# PowerShell (Recommended)
.\scripts\build-and-publish.ps1 -ApiKey "your-nuget-api-key"

# Windows Batch
.\scripts\build-and-publish.cmd "your-nuget-api-key"

# Dry run (test without publishing)
.\scripts\build-and-publish.ps1 -ApiKey "your-nuget-api-key" -DryRun

Manual Build Process

# Restore packages
dotnet restore

# Build project
dotnet build --configuration Release

# Create NuGet package
dotnet pack --configuration Release --output nupkg

# Publish to NuGet
dotnet nuget push "nupkg\BR.Workflow.Contracts.1.0.17.nupkg" --source "https://api.nuget.org/v3/index.json" --api-key "your-api-key"

CI/CD Integration

The package includes scripts for:

• Azure DevOps - Build and release pipelines
• GitHub Actions - Automated workflows
• Jenkins - Build automation
• Local Development - Quick build and test

📖 Documentation

API Documentation

• XML Documentation - Complete API documentation for all public members
• IntelliSense Support - Full IntelliSense in Visual Studio and VS Code
• Code Examples - Comprehensive usage examples in this README

Architecture Documentation

• Clean Architecture - Well-organized structure following SOLID principles
• Service Domain Separation - Clear boundaries between REI, REP, and PT services
• Data Flow Diagrams - Understanding of how data flows through the system

Development Guides

• Getting Started - Quick start guide for new developers
• Best Practices - Guidelines for implementing contracts
• Testing Strategies - Approaches for testing workflow contracts

🤝 Contributing

When extending these contracts:

Code Standards

1. Follow naming conventions (PascalCase for public members)
2. Add comprehensive XML documentation for all public APIs
3. Use nullable reference types appropriately
4. Include data validation attributes where needed
5. Ensure immutability using records
6. Maintain service domain separation
7. Add unit tests for complex validation logic

Pull Request Process

1. Create feature branch from main
2. Implement changes following existing patterns
3. Add tests for new functionality
4. Update documentation as needed
5. Submit pull request with clear description

Testing Requirements

• Unit tests for all new contracts
• Integration tests for workflow patterns
• Validation tests for data models
• Performance tests for critical paths

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Getting Help

• Documentation - Start with this README and XML documentation
• Issues - Report bugs or request features via GitLab issues
• Team Contact - Contact the RealEstate Platform team for direct support

Community

• GitLab Repository - workflow-platform
• NuGet Package - BR.Workflow.Contracts
• Project URL - GitLab Project

🔄 Version History

Current Version: 1.0.17

• Latest Release - September 2024
• .NET Version - 8.0
• Temporal Version - 1.7.0
• Key Features - Complete workflow contracts, activity interfaces, data models

Previous Versions

• 1.0.16 - Initial release with basic contracts
• 1.0.15 - Development version

Built with ❤️ by the Bright River RealEstate Platform Team