# Queue Management

Allegro uses [Laravel Horizon](https://laravel.com/docs/horizon) to supervise background job queues. Horizon manages worker processes, tracks throughput and failure rates, and provides a real-time dashboard.

## Queues[​](#queues "Direct link to Queues")

Allegro defines three queues, processed in strict priority order by the Horizon supervisor.

| Queue           | Priority    | Purpose                                                                  |
| --------------- | ----------- | ------------------------------------------------------------------------ |
| `high`          | 1 (highest) | Latency-sensitive jobs: magic link emails and member profile pre-warming |
| `default`       | 2           | General background jobs (webhooks, etc.)                                 |
| `audience-sync` | 3 (lowest)  | Audience sync provider jobs, dispatched every 5 minutes by the scheduler |

The supervisor uses `balance: false` with queues listed in priority order. Horizon drains `high` before picking up `default` jobs, and `default` before `audience-sync`. Note that priority applies to *selecting the next job* — an in-flight lower-priority job runs to completion before the worker picks up a higher-priority queued job.

## Requirements[​](#requirements "Direct link to Requirements")

Horizon requires Redis. Set `QUEUE_CONNECTION=redis` in your `.env`.

| Variable           | Required | Description                            |
| ------------------ | -------- | -------------------------------------- |
| `QUEUE_CONNECTION` | Yes      | Must be `redis`                        |
| `REDIS_HOST`       | Yes      | Redis host                             |
| `REDIS_PORT`       | Yes      | Redis port (default: `6379`)           |
| `HORIZON_PREFIX`   | No       | Redis key prefix (default: `horizon:`) |

Queue connection

If `QUEUE_CONNECTION` is not `redis`, Horizon starts but no workers are spawned and jobs accumulate unprocessed.

## Starting Horizon[​](#starting-horizon "Direct link to Starting Horizon")

In development:

```bash
composer run dev

```

Horizon starts automatically alongside the web server, Pail, and Vite.

To run Horizon in isolation:

```bash
php artisan horizon

```

## Dashboard[​](#dashboard "Direct link to Dashboard")

The Horizon dashboard is at `/horizon`. It shows live queue metrics, recent and failed jobs, worker status, and throughput graphs.

Dashboard access

The dashboard is restricted to super admins (Alley staff with verified `@alley.com` accounts) via the `viewHorizon` gate registered in `AllegroServiceProvider`. In local environments Horizon's default behavior also permits access without authentication.

## Metrics Snapshots[​](#metrics-snapshots "Direct link to Metrics Snapshots")

`horizon:snapshot` runs every five minutes via the Laravel scheduler. It records queue throughput and wait time metrics used to populate the dashboard graphs. The command must run continuously for the graphs to populate.

## Supervisor Configuration[​](#supervisor-configuration "Direct link to Supervisor Configuration")

The supervisor config lives in `packages/allegro-platform/config/horizon.php`. The defaults apply to all environments; environment-specific overrides are in `environments.production` and `environments.local`.

| Key            | Default                                        | Description                                     |
| -------------- | ---------------------------------------------- | ----------------------------------------------- |
| `balance`      | `false`                                        | Strict queue-order priority (not auto-balanced) |
| `queue`        | `['high', 'default', 'audience-sync']`         | Queue processing order, highest priority first  |
| `maxProcesses` | `1` (local) / `5` (staging) / `5` (production) | Maximum worker processes                        |
| `tries`        | `1`                                            | Job attempts before marking as failed           |
| `timeout`      | `60`                                           | Seconds before a job is considered timed out    |

To publish the config for local customization:

```bash
php artisan vendor:publish --tag=horizon-config

```