# `PhoenixKit.Modules.Emails.Supervisor`
[🔗](https://github.com/BeamLabEU/phoenix_kit_emails/blob/0.4.2/lib/phoenix_kit/modules/emails/supervisor.ex#L1)

Supervisor for PhoenixKit email tracking system.

This module manages all processes necessary for email tracking:
- Bootstraps every registered `EventTracker` (SES, Brevo, …) at boot via
  `EventTrackerReconciler.reconcile/0` — a tracker's chain starts iff
  its own `eligible?/0 and enabled?/0` gate is satisfied. Boot reconcile
  is latency polish (spec §4.3): it makes an eligible tracker start
  immediately instead of waiting for the periodic reconcile Cron
  (`EventTrackerReconcileWorker`), which is the actual correctness
  backbone.
- Registers the unified email provider
- Additional processes (metrics, archiving, etc.)

## Integration into Parent Application

Add supervisor to your application's supervision tree:

    # In lib/your_app/application.ex
    def start(_type, _args) do
      children = [
        # ... your other processes

        # PhoenixKit Email Tracking
        PhoenixKit.Modules.Emails.Supervisor
      ]

      opts = [strategy: :one_for_one, name: YourApp.Supervisor]
      Supervisor.start_link(children, opts)
    end

## Configuration

Supervisor automatically reads settings from PhoenixKit Settings:

- `sqs_polling_enabled` / SES events / queue URL — SQS chain boot gate
- `brevo_events_enabled` — Brevo chain boot gate
- `email_enabled` — system switch (both chains)
- polling intervals and other provider settings

## Process Management

Both pollers are driven entirely by Oban and can be toggled at runtime
without an application restart:

    PhoenixKit.Modules.Emails.SQSPollingManager.enable_polling()
    PhoenixKit.Modules.Emails.SQSPollingManager.disable_polling()
    PhoenixKit.Modules.Emails.BrevoPollingManager.enable_polling()
    PhoenixKit.Modules.Emails.BrevoPollingManager.disable_polling()

Boot re-inserts each enabled chain via `enable_polling/0` so a dead
chain (no queued job after a crash or bad deploy) self-heals when the
setting is still on. If a next tick is already scheduled, the managers'
unique/replace insert moves it to run now rather than appending a
second row.

## Monitoring

Supervisor provides information about process state:

    # Get list of child processes
    Supervisor.which_children(PhoenixKit.Modules.Emails.Supervisor)

    # Get process count
    Supervisor.count_children(PhoenixKit.Modules.Emails.Supervisor)

# `child_spec`

Returns child spec for integration into parent supervisor.

This function is used when you want more precise control
over email tracking integration in your application.

## Examples

    # In lib/your_app/application.ex
    def start(_type, _args) do
      children = [
        # ... other processes
        PhoenixKit.Modules.Emails.Supervisor.child_spec([])
      ]

      Supervisor.start_link(children, strategy: :one_for_one)
    end

# `start_link`

Starts supervisor for email tracking system.

## Options

- `:name` - supervisor process name (defaults to `__MODULE__`)

## Examples

    {:ok, pid} = PhoenixKit.Modules.Emails.Supervisor.start_link()

# `system_status`

Returns information about email tracking system status.

## Examples

    iex> PhoenixKit.Modules.Emails.Supervisor.system_status()
    %{
      supervisor_running: true,
      polling_status: %{enabled: true, pending_jobs: 1, ...},
      brevo_polling_status: %{enabled: true, pending_jobs: 1, ...},
      children_count: 0
    }

---

*Consult [api-reference.md](api-reference.md) for complete listing*