# arnoldasgudas/hangfire.mysqlstorage architecture

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

- Interactive diagram: https://gitdiagram.com/arnoldasgudas/hangfire.mysqlstorage
- Repository: https://github.com/arnoldasgudas/hangfire.mysqlstorage

## Overview

##### Project's Main Purpose and Type
- The project is a library (and accompanying tests) that implements MySQL-based storage for Hangfire.
- Its primary function is to provide the necessary components to store job data, manage queues, tracking counters, set up locks, and enable monitoring for Hangfire jobs.
- The project integrates with Hangfire’s configuration (via GlobalConfiguration.Configuration.UseStorage) and dashboard, meaning the design should show how it plugs into the larger Hangfire system.

##### File Structure
- Two primary top-level directories indicate different layers:
- Hangfire.MySql: Contains core implementation files.
- Hangfire.MySql.Tests: Contains the unit and integration tests structured into modules that correspond to different components.
- Within Hangfire.MySql, the following components are clearly segmented:
- Entities: Data models for jobs, servers, job parameters, job state, etc.
- JobQueue: Contains implementations for managing job queues (interfaces and concrete classes like MySqlJobQueue, MySqlFetchedJob, etc.).
- Monitoring: Contains the monitoring API implementations, used to integrate with the Hangfire dashboard.
- Others: Files like MySqlStorage, MySqlStorageConnection, MySqlWriteOnlyTransaction, CountersAggregator, ExpirationManager, and distributed lock implementations indicate support for transactional operations, expiration handling, counter aggregation, and thread safety.
- Additional utility and configuration files (such as app.config and scripts for packaging) indicate build/deployment aids but are not central to the runtime architecture.

##### Key Components and Their Roles
- Core Storage Component (MySqlStorage): The heart of the system – it registers the storage implementation in Hangfire and abstracts the mechanics of interacting with the MySQL database.
- Storage Connection (MySqlStorageConnection): Manages database connections and API calls to perform CRUD operations on job data.
- Transaction Management (MySqlWriteOnlyTransaction and related classes): Provide safe modifications to the storage ensuring consistency.
- Job Queue (MySqlJobQueue and related classes): Handles enqueuing, dequeuing, and fetching of jobs and supports job queue monitoring.
- Monitoring API (MySqlMonitoringApi): Exposes retrieval methods for Hangfire’s dashboard to display job statistics, monitors, and server information.
- Distributed Locking (MySqlDistributedLock and MySqlDistributedLockException): Ensures that only one process can update a given piece of data (important in a multi-server setup).

##### Relationships and Interactions
- Hangfire.MySql (the storage library) is meant to be instantiated by the Hangfire configuration code in a .NET application.
- When a Hangfire job is submitted, components in the library:
- Use MySqlStorage to create a connection via MySqlStorageConnection.
- Manage job queues through interfaces in the JobQueue folder.
- Regularly check and expire jobs using the ExpirationManager and manage counters using the CountersAggregator.
- Provide monitoring data to the Hangfire dashboard via MySqlMonitoringApi.
- The test suite (in Hangfire.MySql.Tests) mirrors these areas by verifying interactions, state management, and API responses.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Different aspects of storage (connection, transactions, job queuing, monitoring, entity management) are segregated into separate classes and namespaces.
- Interface-based Design: Abstract interfaces for job queues and monitoring APIs allow for easier testing and future extensibility.
- Modular Design: Specific components (like the distributed locking mechanism or schema preparation) are encapsulated within their own classes, which can be diagrammed as separate modules.
- Integration with External Systems: The design shows clear touch points for integration (e.g., Hangfire dashboard), which should be represented as external dependencies.

##### Technologies and Frameworks
- .NET, as it is designed for Hangfire.
- MySQL: As the storage backend.
- Hangfire API Interfaces: The library implements required protocols for Hangfire to run persistent storage operations.
- Testing frameworks integrated via the Hangfire.MySql.Tests project to ensure robustness.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    A["Hangfire Config"]:::external
    Y["Hangfire Dashboard"]:::external
    X["MySQL Database"]:::external

    %% Core Storage Module
    B["MySqlStorage"]:::core

    %% Storage Connection Module
    C["MySqlStorageConnection"]:::core

    %% Transaction Management
    D["MySqlWriteOnlyTransaction"]:::transaction

    %% Job Queue Management Subgraph
    subgraph "Job Queue Management"
        E["MySqlJobQueue"]:::jobQueue
        F["MySqlFetchedJob"]:::jobQueue
        G["MySqlJobQueueMonitoringApi"]:::jobQueue
        H["MySqlJobQueueProvider"]:::jobQueue
    end

    %% Monitoring Module
    I["MySqlMonitoringApi"]:::monitoring

    %% Distributed Locking Subgraph
    subgraph "Distributed Locking"
        J["MySqlDistributedLock"]:::locking
        K["MySqlDistributedLockException"]:::locking
    end

    %% Utility and Support Modules
    L["Entity Models"]:::utility
    M["CountersAggregator"]:::utility
    N["ExpirationManager"]:::utility

    %% Schema Installation Subgraph
    subgraph "Schema Installation"
        O1["Install.sql"]:::installer
        O2["MySqlObjectsInstaller"]:::installer
    end

    %% Test Suite
    Z["Hangfire.MySql.Tests"]:::external

    %% Flow & Relationships
    A -->|"configures"| B
    B -->|"creates connection via"| C
    C -->|"CRUD Operations"| X

    B -->|"initiates transaction via"| D
    B -->|"delegates job queuing to"| E
    E -->|"fetches job using"| F
    E -->|"monitored by"| G
    E -->|"provided by"| H
    B -->|"exposes monitoring via"| I
    Y -->|"queries monitoring"| I

    B -->|"applies distributed locking through"| J
    J -->|"throws exception"| K

    B -->|"utilizes data models in"| L
    B -->|"aggregates metrics via"| M
    B -->|"handles job expiration via"| N

    B -->|"installs schema using"| O1
    O1 --> O2

    %% Test Suite verifies interactions
    Z -->|"tests core"| B
    Z -->|"tests job queue"| E
    Z -->|"tests monitoring"| I

    %% Click Events
    click B "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/MySqlStorage.cs"
    click C "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/MySqlStorageConnection.cs"
    click D "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/MySqlWriteOnlyTransaction.cs"
    click E "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/JobQueue/MySqlJobQueue.cs"
    click F "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/JobQueue/MySqlFetchedJob.cs"
    click G "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/JobQueue/MySqlJobQueueMonitoringApi.cs"
    click H "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/JobQueue/MySqlJobQueueProvider.cs"
    click I "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/Monitoring/MySqlMonitoringApi.cs"
    click J "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/MySqlDistributedLock.cs"
    click K "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/MySqlDistributedLockException.cs"
    click L "https://github.com/arnoldasgudas/hangfire.mysqlstorage/tree/master/Hangfire.MySql/Entities"
    click M "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/CountersAggregator.cs"
    click N "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/ExpirationManager.cs"
    click O1 "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/Install.sql"
    click O2 "https://github.com/arnoldasgudas/hangfire.mysqlstorage/blob/master/Hangfire.MySql/MySqlObjectsInstaller.cs"

    %% Styles
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:2px
    classDef core fill:#fdd017,stroke:#333,stroke-width:2px
    classDef transaction fill:#ff9999,stroke:#333,stroke-width:2px
    classDef jobQueue fill:#99ccff,stroke:#333,stroke-width:2px
    classDef monitoring fill:#ccffcc,stroke:#333,stroke-width:2px
    classDef locking fill:#ffcc99,stroke:#333,stroke-width:2px
    classDef utility fill:#ccccff,stroke:#333,stroke-width:2px
    classDef installer fill:#ffb6c1,stroke:#333,stroke-width:2px
```
