# mikasjp/busybee architecture

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

- Interactive diagram: https://gitdiagram.com/mikasjp/busybee
- Repository: https://github.com/mikasjp/busybee

## Overview

##### Project type and purpose
- BusyBee is an open-source .NET library for high-performance background job processing.
- It exposes a fluent API for dependency injection, queue configuration, job timeouts, and observability.

##### Main components
- **DemoApp** (example client): Web API endpoints that enqueue jobs.
- **DI Container**: .NET IServiceCollection that wires up BusyBee.
- **IBackgroundQueue**: abstraction for enqueuing jobs.
- **Queue**: in-memory channel based queue (bounded or unbounded).
- **ProcessorService**: background hosted service that pulls jobs.
- **JobRunner**: executes the job delegate and handles cancellation/timeouts/failures.
- **Observability**: emits traces & metrics (OpenTelemetry) and logs.
- **External systems**: OpenTelemetry Collector, Prometheus, Seq/log sink.

##### Relationships & data flow
- DemoApp HTTP endpoint → enqueues job via IBackgroundQueue
- QueueFactory creates Queue → JobWrapper placed on Channel
- ProcessorService reads from Channel → invokes JobRunner
- JobRunner uses IJobTimeoutHandler/IJobFailureHandler → notifies Observability
- Observability exports metrics/traces to OTEL & logs to Seq
- Prometheus scrapes the metrics endpoint

##### Architectural highlights
- **Dependency Injection**: everything registers via `AddBusyBee()`
- **Channel-based Queues**: unbounded/bounded with overflow strategies
- **Hosted Service Pattern**: .NET background service for processing
- **Observability**: OpenTelemetry instrumentation and Prometheus integration
- **Extensibility**: pluggable failure/timeout handlers

## Diagram (Mermaid)

```mermaid
graph TB
  %% DemoApp (Client)
  subgraph "DemoApp (Client)"
    direction TB
    DemoAppDir["DemoApp"]:::client
    EnqueueEndpoint["Enqueue Job Endpoint"]:::client
    GetLogEndpoint["Get Queue Log Endpoint"]:::client
    OpenTelModule["OpenTelemetry Module"]:::client
    PromConfig["Prometheus Config"]:::client
    DockerCompose["Docker Compose (OTEL & Prometheus)"]:::client
  end

  %% BusyBee Library
  subgraph "BusyBee Library"
    direction TB
    BusyBeeBuilder["AddBusyBee DI Setup"]:::library
    BusyBeeModule["Dependency Injection Module"]:::library
    IBackgroundQueue["IBackgroundQueue"]:::library
    JobWrapper["JobWrapper (Channel Message)"]:::library
    QueueImpl["Queue Implementation"]:::library
    QueueOptions["Queue Options & Overflow"]:::library
    QueueOverflowEx["QueueCapacityExceededException"]:::library
    ProcessorService["ProcessorService (HostedService)"]:::library
    JobRunner["JobRunner (Exec + Timeout/Failure)"]:::library
    JobContext["JobContext"]:::library
    ProcessorOptions["ProcessorOptions"]:::library
    SlotsTracker["SlotsTracker"]:::library
    Metrics["Observability–Metrics API"]:::library
    MetricsConstants["Observability–Metrics Constants"]:::library
    TracingConstants["Observability–Tracing Constants"]:::library
    JobFailureHandlerAbst["IJobFailureHandler"]:::library
    JobTimeoutHandlerAbst["IJobTimeoutHandler"]:::library
    DemoAppFailureHandler["DemoApp JobFailureHandler"]:::client
    DemoAppTimeoutHandler["DemoApp JobTimeoutHandler"]:::client
  end

  %% External Systems
  subgraph "External Systems"
    direction TB
    OTEL["OpenTelemetry Collector"]:::external
    PROM["Prometheus"]:::external
    LOG["Seq / Logging Sink"]:::external
  end

  %% Data Flow
  EnqueueEndpoint -->|"Enqueue(job)"| IBackgroundQueue
  IBackgroundQueue -->|"resolve"| IBackgroundQueue
  IBackgroundQueue -->|enqueue| JobWrapper
  JobWrapper -->|enqueue| QueueImpl
  QueueImpl -->|dequeue| ProcessorService
  ProcessorService -->|invoke| JobRunner
  JobRunner -->|emit metrics/traces| Metrics
  Metrics --> OTEL
  Metrics --> LOG
  OTEL --> PROM

  %% Click Events
  click DemoAppDir "https://github.com/mikasjp/busybee/tree/main/examples/DemoApp"
  click EnqueueEndpoint "https://github.com/mikasjp/busybee/blob/main/examples/DemoApp/Endpoints/EnqueueJobEndpoint.cs"
  click GetLogEndpoint "https://github.com/mikasjp/busybee/blob/main/examples/DemoApp/Endpoints/GetQueueExecutionLogEndpoint.cs"
  click OpenTelModule "https://github.com/mikasjp/busybee/blob/main/examples/DemoApp/OpenTelemetryModule.cs"
  click PromConfig "https://github.com/mikasjp/busybee/blob/main/examples/DemoApp/prometheus.yml"
  click DockerCompose "https://github.com/mikasjp/busybee/blob/main/examples/DemoApp/compose.yaml"
  click BusyBeeBuilder "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/BusyBeeBuilder.cs"
  click BusyBeeModule "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/BusyBeeModule.cs"
  click IBackgroundQueue "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Queue/IBackgroundQueue.cs"
  click JobWrapper "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Queue/JobWrapper.cs"
  click QueueImpl "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Queue/Queue.cs"
  click QueueOptions "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Queue/QueueOptions.cs"
  click QueueOverflowEx "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Queue/Exceptions/QueueCapacityExceededException.cs"
  click ProcessorService "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Processor/ProcessorService.cs"
  click JobRunner "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Processor/JobRunner.cs"
  click JobContext "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Processor/JobContext.cs"
  click ProcessorOptions "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Processor/ProcessorOptions.cs"
  click SlotsTracker "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Processor/SlotsTracker.cs"
  click Metrics "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Observability/Metrics.cs"
  click MetricsConstants "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Observability/MetricsConstants.cs"
  click TracingConstants "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Observability/TracingConstants.cs"
  click JobFailureHandlerAbst "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Abstractions/IJobFailureHandler.cs"
  click JobTimeoutHandlerAbst "https://github.com/mikasjp/busybee/blob/main/src/BusyBee/Abstractions/IJobTimeoutHandler.cs"
  click DemoAppFailureHandler "https://github.com/mikasjp/busybee/blob/main/examples/DemoApp/JobFailureHandler.cs"
  click DemoAppTimeoutHandler "https://github.com/mikasjp/busybee/blob/main/examples/DemoApp/JobTimeoutHandler.cs"

  %% Styles
  classDef client fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
  classDef library fill:#FFF4C1,stroke:#D99B00,color:#7A5901;
  classDef external fill:#E0F4E0,stroke:#2E8B57,color:#2E8B57;
```
