BR.Workflow.Contracts 1.0.15

BR.Workflow.Contracts

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

🏗️ Architecture Overview

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

• REI (Real Estate Ingestor) - Event validation and blob operations
• REP (Real Estate Processor) - Order processing and business logic
• PT (Payload Transformer) - Data transformation for external services

✨ Features

• ✅ Clean Architecture - Well-organized contracts following SOLID principles
• ✅ Service Domain Separation - Clear boundaries between REI, REP, and PT services
• ✅ Temporal Integration - Native support for Temporal.io workflows and activities
• ✅ .NET 8 Compatible - Built with the latest .NET features
• ✅ 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

📦 Installation

dotnet add package BR.Workflow.Contracts

🏛️ Project Structure

BR.Workflow.Contracts/
├── Workflows/                    # Workflow interfaces and models
│   ├── IStartRealEstateWorkflow.cs
│   └── Models/
│       └── WorkflowOutput.cs
│
├── Activities/                   # Activity interfaces by service domain
│   ├── REI/                     # Real Estate Ingestor
│   │   ├── IValidateEventActivity.cs
│   │   ├── IDownloadBlobActivity.cs
│   │   └── IUpdateOrderStatusInBlobActivity.cs
│   │
│   ├── REP/                     # Real Estate Processor
│   │   ├── IValidateSchemaTemplateActivity.cs
│   │   ├── IDetermineActionTypeActivity.cs
│   │   ├── ICreateOrderActivity.cs
│   │   ├── IUpdateOrderActivity.cs
│   │   ├── IApproveOrderActivity.cs
│   │   ├── IRejectOrderActivity.cs
│   │   ├── INotifyClientActivity.cs
│   │   ├── IUpdateDbActivity.cs
│   │   └── ICallApiGatewayActivity.cs
│   │
│   └── PT/                      # Payload Transformer
│       └── ITransformPayloadActivity.cs
│
├── Models/                       # Data models organized by service domain
│   ├── Common/                   # Shared models across all services
│   ├── Kafka/                    # Kafka payload and workflow input models
│   │   ├── WorkflowInput.cs      # Main workflow input (Kafka payload)
│   │   ├── EventInfo.cs          # Event metadata
│   │   ├── ClientInfo.cs         # Client information
│   │   ├── BlobInfo.cs           # Blob storage information
│   │   ├── DeadLetterEvent.cs    # Dead Letter Queue events
│   │   ├── DlqDetails.cs         # DLQ failure details
│   │   └── README.md             # Documentation
│   ├── REI/                      # Real Estate Ingestor models
│   ├── REP/                      # Real Estate Processor models
│   └── PT/                       # Payload Transformer models
│
├── Enums/                        # Enumerations and constants
├── Extensions/                   # Utility extension methods
└── Constants/                    # Configuration and naming constants

🚀 Usage Examples

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<WorkflowOutput> ExecuteAsync(WorkflowInput input)
    {
        // Workflow implementation using Kafka payload data...
        return new WorkflowOutput
        {
            WorkflowId = Guid.NewGuid(),
            Status = "Completed",
            ClientId = input.Client.Id,
            OrderId = Guid.NewGuid(),
            ActionType = ActionType.Create,
            Audit = new AuditInfo
            {
                CompletedAt = DateTime.UtcNow,
                Errors = Array.Empty<ErrorInfo>()
            }
        };
    }
}

Activity Implementation

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

public class ValidateEventActivity : IValidateEventActivity
{
    public async Task<ValidateEventOutput> ValidateAsync(ValidateEventInput input)
    {
        // Activity implementation...
        return new ValidateEventOutput
        {
            CanProceed = true,
            DuplicateCheck = new DuplicateCheck
            {
                RecentlyDownloaded = false,
                DownloadCount = 0
            },
            ValidationErrors = Array.Empty<ErrorInfo>()
        };
    }
}

Using Extensions

using BR.Workflow.Contracts.Extensions;

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

// Validate contract inputs
if (!input.IsValid())
{
    var errors = input.GetValidationErrors();
    // Handle validation errors...
}

🔧 Service Domain Responsibilities

REI (Real Estate Ingestion)

• Event Validation - Validate incoming events and check for duplicates
• Blob Operations - Download and manage blob content from Azure Storage
• Status Updates - Update order status in blob storage

REP (Real Estate Processing)

• Schema Validation - Validate data against business schemas
• Action Determination - Determine processing action type
• Order Management - Create, update, approve, and reject orders
• Client Communication - Notify clients of order status changes
• Database Operations - Update processing status in database
• API Integration - Communicate with external services via API Gateway

PT (Property Transformation)

• Data Transformation - Transform data between different service formats
• Schema Mapping - Map data from REPS format to external service format
• Validation - Validate transformed data against target schemas

📨 Kafka Integration

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

Kafka Payload Models (Models/Kafka/)

• WorkflowInput - Main workflow input from Kafka messages
• EventInfo - Event metadata with correlation tracking
• ClientInfo - Client identification and reference data
• BlobInfo - Azure Blob Storage information

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<WorkflowInput>(kafkaMessage);

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

📋 Contracts Included

Workflows

• IStartRealEstateWorkflow - Main workflow orchestration interface

Activities (13 Total)

• REI (3): ValidateEvent, DownloadBlob, UpdateOrderStatusInBlob
• REP (9): ValidateSchema, DetermineAction, CreateOrder, UpdateOrder, ApproveOrder, RejectOrder, NotifyClient, UpdateDb, CallApiGateway
• PT (1): TransformPayload

Models

• Workflow Models: Input/Output contracts for workflow orchestration
• Activity Models: Input/Output contracts for all activities
• Common Models: Shared data structures and validation models

Enums

• ActionType, BrightRiverStatus, OrderStatus
• ValidationSeverity, DeliveryStatus, HttpMethod, NotificationType

🎯 Clean Architecture Benefits

• 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

🚀 Ready for Production

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

• ✅ PascalCase naming conventions
• ✅ Async/await patterns for I/O operations
• ✅ Comprehensive error handling with custom exceptions
• ✅ Dependency injection principles
• ✅ Modern C# features (records, pattern matching, nullable references)
• ✅ Comprehensive XML documentation
• ✅ Thread-safe immutable data contracts

📖 Documentation

• XML Documentation - Complete API documentation for all public members
• Clean Architecture - Well-organized structure following SOLID principles
• Service Domain Separation - Clear boundaries between REI, REP, and PT services

🤝 Contributing

When extending these contracts:

1. Follow the existing naming conventions (PascalCase)
2. Add comprehensive XML documentation
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

📄 License

This project is licensed under the MIT License.

🆘 Support

For questions and support, please refer to the project documentation or contact the RealEstate Platform team.