# na-sabbag/task-runner-sharp architecture

> Architecture diagram of the GitHub repository na-sabbag/task-runner-sharp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/na-sabbag/task-runner-sharp
- Repository: https://github.com/na-sabbag/task-runner-sharp

## Overview

##### Project Type and Purpose
- TaskRunnerSharp is a .NET class-library (distributed via NuGet) whose sole purpose is to let client code register, run, monitor, and gather results from multiple synchronous or asynchronous tasks.
- It exposes a minimal public API (ITaskRunner) and a concrete implementation (TaskRunner) that manages tasks, thread‐safety, logging, and result aggregation.

##### File Structure
- Top-level:
- TaskRunnerSharp.sln – Visual Studio solution
- README.md, LICENSE, .gitignore
- src/
- ITaskRunner.cs – public interface defining Add(…), Run/RunAsync(), Results, Logs, Clear()
- TaskRunner.cs – core implementation of ITaskRunner
- TaskRunnerSharp.csproj – .NET class library project file
- tests/
- TaskRunnerSharp.Tests.csproj – test project
- TaskRunnerTests.cs – unit tests for core behaviors
- No web-UI or database subfolders – this is a pure in-process library.

##### README for Additional Insights
- Key features:
- Orchestrate both Task and Task<T>
- Synchronous and asynchronous execution
- Thread-safe operations
- Execution logging (lifecycle events for each task)
- Result aggregation for typed tasks
- Usage pattern: client creates a runner, calls Add(…), then Run()/RunAsync(), then inspects Results and Logs, then Clear().

a. Main Components to Show
1. Client Application – any .NET process that consumes the library
2. Public API Layer – ITaskRunner interface
3. Core Engine – TaskRunner class
- Task Registry / Queue
- Execution Engine (spawns and awaits System.Threading.Tasks)
- Result Aggregator
- Logging Component
- Thread‐Safety Mechanism (locks or concurrent collections)
4. Underlying .NET Task Infrastructure – System.Threading.Tasks.Task & Task<T>
5. Extension Points – custom implementations of ITaskRunner or middleware hooks (if any)
6. Test Harness – indicates how tests reference the public API and validate internal behavior

b. Relationships and Data Flow
- The Client invokes ITaskRunner.Add(…) → tasks land in the Task Registry.
- On Run()/RunAsync(), Core Engine picks tasks from the registry, hands them to the .NET Task infrastructure (Task.Run or direct invocation).
- As each Task completes, Execution Engine sends completion events to:
- Result Aggregator (for typed results)
- Logging Component (for lifecycle logs)
- Results and Logs are exposed back to the Client via IReadOnlyCollections.
- Clear() flushes the registry, results, and logs.

c. Architectural Patterns and Principles
- Interface‐driven design: ITaskRunner decouples client consumers from concrete implementation.
- Single Responsibility: separate modules for task orchestration, logging, and result aggregation.
- Thread safety via lock‐free or concurrent collections.
- Liskov Substitution: any ITaskRunner implementer can replace the default TaskRunner.

d. Relevant Technologies, Frameworks, Libraries
- C# 8+ / .NET Core or .NET Standard for maximum compatibility
- System.Threading.Tasks for parallelism
- Concurrent collections (e.g., ConcurrentQueue, ConcurrentBag)
- xUnit or MSTest for tests (per csproj)
- NuGet packaging for distribution

##### Detail
- Break the Core Engine into subcomponents to show responsibilities clearly.
- Thread‐safety boundaries (e.g., which collections are thread-safe).
- Both synchronous (Run) and asynchronous (RunAsync) flows if space permits.
- Don’t over-complicate: if a module isn’t in the codebase, leave it out.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Development Artifacts"
        SLN["TaskRunnerSharp.sln"]:::external
        README["README.md"]:::external
        LICENSE["LICENSE"]:::external
        PROJ["TaskRunnerSharp.csproj"]:::core
    end

    subgraph "Client"
        ClientApp["Client Application"]:::external
    end

    subgraph "Public API"
        Interface["ITaskRunner"]:::publicApi
    end

    subgraph "Core Engine"
        TR["TaskRunner"]:::core
        subgraph "Internal Modules"
            Registry["Task Registry"]:::core
            ExecEngine["Execution Engine"]:::core
            Aggregator["Result Aggregator"]:::core
            Logger["Logging Component"]:::core
            ThreadSafety["Thread-Safety Mechanism"]:::core
        end
    end

    subgraph "BCL Dependencies"
        TaskInfra["System.Threading.Tasks"]:::bcl
        Concurrent["Concurrent Collections"]:::bcl
    end

    subgraph "Test Harness"
        TestsProj["TaskRunnerSharp.Tests.csproj"]:::external
        Tests["TaskRunnerTests"]:::external
    end

    ClientApp -->|"uses"| Interface
    Interface -->|"implemented by"| TR
    TR -->|"manages tasks in"| Registry
    Registry -->|"feeds"| ExecEngine
    ExecEngine -->|"spawns"| TaskInfra
    ExecEngine -->|"uses"| Concurrent
    TaskInfra -->|"completes to"| Aggregator
    TaskInfra -->|"fires logs to"| Logger
    Aggregator -->|"exposes Results to"| ClientApp
    Logger -->|"exposes Logs to"| ClientApp
    TR -->|"aggregates via"| Aggregator
    TR -->|"logs via"| Logger

    click Interface "https://github.com/na-sabbag/task-runner-sharp/blob/main/src/ITaskRunner.cs"
    click TR "https://github.com/na-sabbag/task-runner-sharp/blob/main/src/TaskRunner.cs"
    click PROJ "https://github.com/na-sabbag/task-runner-sharp/blob/main/src/TaskRunnerSharp.csproj"
    click SLN "https://github.com/na-sabbag/task-runner-sharp/blob/main/TaskRunnerSharp.sln"
    click README "https://github.com/na-sabbag/task-runner-sharp/blob/main/README.md"
    click LICENSE "https://github.com/na-sabbag/task-runner-sharp/tree/main/LICENSE"
    click TestsProj "https://github.com/na-sabbag/task-runner-sharp/blob/main/tests/TaskRunnerSharp.Tests/TaskRunnerSharp.Tests.csproj"
    click Tests "https://github.com/na-sabbag/task-runner-sharp/blob/main/tests/TaskRunnerTests.cs"

    classDef publicApi fill:#add8e6,stroke:#000
    classDef core fill:#90ee90,stroke:#000
    classDef bcl fill:#d3d3d3,stroke:#000
    classDef external fill:#ffa500,stroke:#000
```
