# calabonga/calabonga.workexecutor architecture

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

- Interactive diagram: https://gitdiagram.com/calabonga/calabonga.workexecutor
- Repository: https://github.com/calabonga/calabonga.workexecutor

## Overview

Step 1: Identify the Main Components

- Core Library (Calabonga.WorkExecutor)
- Base: Contains interfaces (IWork, IWorkExecutor, IWorkMetadata) and the abstract WorkBase class that all work implementations extend.
- Configurations: Holds the configuration abstractions (IWorkExecutorConfiguration) and implementations (DefaultConfiguration) for controlling work execution behavior.
- Exceptions: Defines custom exceptions such as WorkExecutorException.
- Reports: Contains various report classes (WorkSuccessReport, WorkFailedReport, WorkErrorReport, WorkCancelledReport) and the interfaces for reporting (IWorkReport) which describe work results.
- The central WorkExecutor class that orchestrates the execution of registered works based upon their order and result conditions.

- Work Implementations
- Several example work classes such as Work1, Work2, and Work3, each derived from WorkBase that simulates retrieving an address result from a remote service.
- Each work returns a specific type of report based on execution results (success, failure, error).

- Sample Application (Calabonga.ConsoleWorker)
- A console application that wires up all the components using dependency injection.
- Includes app settings, a main Program.cs, and code to register and resolve the AddressWorkExecutor with its configuration and work implementations.
- Acts as a demonstration of how a consuming client would utilize the NuGet package.

- Test Suite (Calabonga.WorkExecutor.Tests)
- A dedicated test project that includes unit tests (using fixtures, for example) ensuring that the work executor and its components behave as expected.

Step 2: Determine the Relationships and Interactions

- The Console Application sets up a Dependency Injection (DI) container:
- Registers the AddressWorkExecutor (which itself derives from the WorkExecutor<T, IConfiguration> base).
- Registers individual works (Work1, Work2, Work3) as IWork<AddressResult> implementations.
- Registers the configuration (IWorkExecutorConfiguration, provided by DefaultConfiguration).

- The AddressWorkExecutor is resolved by the DI container and acts as the coordinating component:
- It retrieves the list of IWork implementations, orders them by OrderIndex, and starts executing them one by one.
- The execution results are captured as specialized WorkReports (success, failure, etc.).

- Reports and Error Handling:
- Each Work returns a report, which is aggregated by the WorkExecutor.
- If a work fails or returns errors, the WorkExecutor can decide to try the next work or signal overall failure.
- Errors and results are logged in the console sample application, demonstrating both success flows and error logging.

Step 3: Highlight Core Architectural Patterns and Technologies

- Design Patterns:
- Template Method: The abstract WorkBase class defines the overall algorithm for work execution, while Work1, Work2, and Work3 provide specific implementations.
- Dependency Injection: Used extensively in the Console application to decouple components.
- Strategy/Chain of Responsibility: The work executor runs different strategies (works) in sequence, stopping when one succeeds.

- Technologies and Frameworks:
- .NET with its DI container and configuration management.
- CI/CD integration is evident from the .github/workflows configuration.
- NuGet packaging to distribute the library.

a. Main Components to Represent:
- Base Module (Interfaces and abstract classes)
- Configurations
- Exceptions
- Reports
- Central WorkExecutor Class

b. Relationships / Interactions:
- A connection from the WorkExecutor to configuration and error handling modules.

c. Important Architectural Patterns / Design Principles:
- Areas using descriptive labels like "Dependency Injection", "Work Execution Pipeline", and "Fallback/Error Handling".
- Sequential execution order indicated by the OrderIndex property.

d. Fair Detail in Representation:
- That every component is clearly labeled.

- Since this is a NuGet package providing a work execution framework:
- Core library and illustrate its extensibility.
- How new “work” components can be added and ordered.
- How the Console Application uses DI to assemble the work execution chain, and how errors and success are managed and logged.

Final Instructions for the Principal Software Engineer:

1. Highest level by placing the “Console Application” and “DI Container” at the top. From there, show that the container resolves the “AddressWorkExecutor” component.
5. A side component (or layer) for unit tests (Calabonga.WorkExecutor.Tests) to indicate test coverage and validation.
- The entry point (Console Application)
- The core executable component (WorkExecutor)
- The various work implementations and reporting mechanisms.
7. Fallback logic and error flow by showing how the process continues (or stops) based on WorkReport outcomes.
8. Finally, incorporate any CI/CD or external service simulation aspects (like the use of a .env file or simulated delays in Work implementations), if relevant.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        ConsoleApp["Console Application (Calabonga.ConsoleWorker)"]
        DI["DI Container Setup"]
        AddressWorkExecutor["AddressWorkExecutor"]
        ConsoleApp --> DI
        DI --> AddressWorkExecutor
    end

    subgraph "Calabonga.WorkExecutor Core Library"
        Base["Base Module (Interfaces & Abstract Classes)"]
        Config["Configurations"]
        Exceptions["Exceptions"]
        subgraph "Reports Module"
            ReportsBase["Reports Base"]
            ReportCancelled["WorkCancelledReport"]
            ReportError["WorkErrorReport"]
            ReportFailed["WorkFailedReport"]
            ReportSuccess["WorkSuccessReport"]
        end
        WorkExecutor["WorkExecutor (Central)"]
    end

    subgraph "Work Implementations"
        Work1["Work1 (OrderIndex:1)"]
        Work2["Work2 (OrderIndex:2)"]
        Work3["Work3 (OrderIndex:3)"]
    end

    subgraph "Test Suite"
        Tests["Test Suite (Calabonga.WorkExecutor.Tests)"]
        Tests1["AddressWorkExecutorTests"]
        TestsFixture["WorkExecutorFixture"]
        Tests --> Tests1
        Tests --> TestsFixture
    end

    %% Connections between layers
    ConsoleApp -- "logs outcome" --> WorkExecutor
    DI -- "resolves" --> WorkExecutor
    AddressWorkExecutor -- "implements" --> WorkExecutor

    %% WorkExecutor executes works
    WorkExecutor -- "executes" --> Work1
    WorkExecutor -- "executes" --> Work2
    WorkExecutor -- "executes" --> Work3

    %% Works return reports to WorkExecutor
    Work1 -- "WorkReport" --> WorkExecutor
    Work2 -- "WorkReport" --> WorkExecutor
    Work3 -- "WorkReport" --> WorkExecutor

    %% WorkExecutor dependencies within Core Library
    WorkExecutor -- "uses" --> Config
    WorkExecutor -- "handles" --> Exceptions
    WorkExecutor -- "aggregates" --> ReportsBase
    ReportsBase --- ReportCancelled
    ReportsBase --- ReportError
    ReportsBase --- ReportFailed
    ReportsBase --- ReportSuccess
    WorkExecutor --- Base

    %% Test suite validation
    Tests -- "validates" --> WorkExecutor

    %% Click Events for Core Library components
    click Base "https://github.com/calabonga/calabonga.workexecutor/tree/main/src/Calabonga.WorkExecutor/Base"
    click Config "https://github.com/calabonga/calabonga.workexecutor/tree/main/src/Calabonga.WorkExecutor/Configurations"
    click Exceptions "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.WorkExecutor/Exceptions/WorkExecutorException.cs"
    click ReportsBase "https://github.com/calabonga/calabonga.workexecutor/tree/main/src/Calabonga.WorkExecutor/Reports/Base"
    click ReportCancelled "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.WorkExecutor/Reports/WorkCancelledReport.cs"
    click ReportError "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.WorkExecutor/Reports/WorkErrorReport.cs"
    click ReportFailed "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.WorkExecutor/Reports/WorkFailedReport.cs"
    click ReportSuccess "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.WorkExecutor/Reports/WorkSuccessReport.cs"
    click WorkExecutor "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.WorkExecutor/WorkExecutor.cs"

    %% Click Events for Work Implementations
    click Work1 "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.ConsoleWorker/App/Work1.cs"
    click Work2 "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.ConsoleWorker/App/Work2.cs"
    click Work3 "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.ConsoleWorker/App/Work3.cs"

    %% Click Events for Console Application
    click ConsoleApp "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.ConsoleWorker/Program.cs"
    click ConsoleApp "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.ConsoleWorker/ConsoleApp.cs"
    click AddressWorkExecutor "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.ConsoleWorker/App/AddressWorkExecutor.cs"

    %% Click Events for Test Suite
    click Tests "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.WorkExecutor.Tests"
    click Tests1 "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.WorkExecutor.Tests/AddressWorkExecutorTests.cs"
    click TestsFixture "https://github.com/calabonga/calabonga.workexecutor/blob/main/src/Calabonga.WorkExecutor.Tests/Fixtures/WorkExecutorFixture.cs"

    %% Styles
    classDef presentation fill:#f9f,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef work fill:#dfd,stroke:#333,stroke-width:2px;
    classDef test fill:#fdd,stroke:#333,stroke-width:2px;

    class ConsoleApp,DI,AddressWorkExecutor presentation;
    class Base,Config,Exceptions,ReportsBase,ReportCancelled,ReportError,ReportFailed,ReportSuccess,WorkExecutor core;
    class Work1,Work2,Work3 work;
    class Tests,Tests1,TestsFixture test;
```
