# jondot/sneakers architecture

> Architecture diagram of the GitHub repository jondot/sneakers, 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/jondot/sneakers
- Repository: https://github.com/jondot/sneakers

## Overview

##### Main Components
- Worker Components – The library’s core is built around a worker model. This includes classes/modules like the worker mixin (found in lib/sneakers/worker.rb), the worker group (lib/sneakers/workergroup.rb), and related classes such as the Publisher (lib/sneakers/publisher.rb) and Queue (lib/sneakers/queue.rb).
- Runner and Spawner – Look at lib/sneakers/runner.rb and lib/sneakers/spawner.rb. These are responsible for launching and managing the worker processes.
- CLI Interface – The command-line interface (lib/sneakers/cli.rb) is responsible for bootstrapping the application and starting the worker processes given the user’s command line arguments.
- Configuration and Middleware – The configuration file (lib/sneakers/configuration.rb) sets up all runtime settings, while middleware components (lib/sneakers/middleware) handle pre- and post-processing aspects such as logging and metrics.
- Metrics and Error Reporting – There are various metrics providers (logging_metrics, newrelic_metrics, statsd_metrics) along with error reporting in classes like lib/sneakers/error_reporter.rb. This illustrates the intentional design of observability into the system.
- Handlers – Modules like maxretry and oneshot (lib/sneakers/handlers) demonstrate how the system is built for robustness by handling message failures.

##### Relationships and Interactions
- Middleware Chain: Indicate how the middleware components wrap around each worker’s execution, intercepting to log, capture metrics, or handle errors.
- Error/Retry Handling: Highlight the role of specialized handlers in case of failures; illustrate decision paths (e.g., retry vs. one-shot treatment for a failed message).

##### Architectural Patterns and Design Principles
- Layered/Modular Architecture: Separate the system into configuration, core worker components, middleware, and external service connectors (RabbitMQ, Redis in examples, Docker for deployment orchestration).
- Extensibility: Emphasize that Sneakers is built as a library where extension points (e.g., custom middleware or handler implementations) are clearly defined.
- Reliability & Observability: Since handling and logging of errors and metrics are critically embedded, illustrate these as cross-cutting concerns across the system.

##### Technologies and Libraries
- Ruby – The primary language, with supporting gems for message brokering (Bunny for RabbitMQ), JSON handling, and Redis usage in examples.
- RabbitMQ – Central to the architecture as the message broker.
- Docker/Docker-Compose – Shown in the file tree by Dockerfile(s) and docker-compose.yml. They illustrate both development and production deployment mechanisms.
- Continuous Integration – Indicated via GitHub workflows and CI configuration files.

- Separate modules for Metrics Providers and Error Handlers that interface with the worker processing.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "Initialization"
        CLI("CLI Interface"):::internal
        Config("Configuration"):::internal
        CLI -->|"loads"| Config
    end

    subgraph "Worker Management"
        Runner("Runner"):::internal
        Spawner("Spawner"):::internal
        Config -->|"initializes"| Runner
        Config -->|"initializes"| Spawner
    end

    subgraph "Worker Components"
        WorkerMixin("Worker Mixin"):::internal
        WorkerGroup("Worker Group"):::internal
        Queue("Queue"):::internal
        Publisher("Publisher"):::internal
        Runner -->|"spawns"| WorkerGroup
        Spawner -->|"manages"| WorkerGroup
        WorkerGroup -->|"uses"| WorkerMixin
        WorkerGroup -->|"fetches_from"| Queue
        WorkerGroup -->|"sends_via"| Publisher
    end

    RabbitMQ("RabbitMQ (Message Broker)"):::external
    RabbitMQ -->|"delivers_message"| Queue

    subgraph "Middleware & Observability"
        Middleware("Middleware"):::middleware
        MetricsProviders("Metrics Providers"):::middleware
        ErrorReporter("Error Reporter"):::middleware
        Handlers("Handlers"):::middleware
        WorkerMixin -->|"wrapped_by"| Middleware
        Middleware -->|"logs_metrics"| MetricsProviders
        WorkerMixin -->|"on_error"| ErrorReporter
        ErrorReporter -->|"triggers"| Handlers
    end

    subgraph "Metrics Providers Details"
        LoggingMetrics("Logging Metrics"):::middleware
        NewRelicMetrics("NewRelic Metrics"):::middleware
        StatsDMetrics("StatsD Metrics"):::middleware
        NullMetrics("Null Metrics"):::middleware
        MetricsProviders --> LoggingMetrics
        MetricsProviders --> NewRelicMetrics
        MetricsProviders --> StatsDMetrics
        MetricsProviders --> NullMetrics
    end

    subgraph "Handlers Details"
        MaxRetry("MaxRetry Handler"):::middleware
        OneShot("OneShot Handler"):::middleware
        Handlers --> MaxRetry
        Handlers --> OneShot
    end

    subgraph "Deployment"
        Docker("Docker"):::external
        CI("Continuous Integration"):::external
        Runner -->|"deployed_in"| Docker
        Runner -->|"tested_by"| CI
    end

    %% Click Events
    click CLI "https://github.com/jondot/sneakers/blob/master/lib/sneakers/cli.rb"
    click Config "https://github.com/jondot/sneakers/blob/master/lib/sneakers/configuration.rb"
    click Runner "https://github.com/jondot/sneakers/blob/master/lib/sneakers/runner.rb"
    click Spawner "https://github.com/jondot/sneakers/blob/master/lib/sneakers/spawner.rb"
    click WorkerMixin "https://github.com/jondot/sneakers/blob/master/lib/sneakers/worker.rb"
    click WorkerGroup "https://github.com/jondot/sneakers/blob/master/lib/sneakers/workergroup.rb"
    click Publisher "https://github.com/jondot/sneakers/blob/master/lib/sneakers/publisher.rb"
    click Queue "https://github.com/jondot/sneakers/blob/master/lib/sneakers/queue.rb"
    click Middleware "https://github.com/jondot/sneakers/tree/master/lib/sneakers/middleware"
    click LoggingMetrics "https://github.com/jondot/sneakers/blob/master/lib/sneakers/metrics/logging_metrics.rb"
    click NewRelicMetrics "https://github.com/jondot/sneakers/blob/master/lib/sneakers/metrics/newrelic_metrics.rb"
    click StatsDMetrics "https://github.com/jondot/sneakers/blob/master/lib/sneakers/metrics/statsd_metrics.rb"
    click NullMetrics "https://github.com/jondot/sneakers/blob/master/lib/sneakers/metrics/null_metrics.rb"
    click ErrorReporter "https://github.com/jondot/sneakers/blob/master/lib/sneakers/error_reporter.rb"
    click MaxRetry "https://github.com/jondot/sneakers/blob/master/lib/sneakers/handlers/maxretry.rb"
    click OneShot "https://github.com/jondot/sneakers/blob/master/lib/sneakers/handlers/oneshot.rb"

    %% Styles
    classDef internal fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef external fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef middleware fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
```
