Notifications & alerting

Status: Accepted · Audience: Both · Area: B — Running it

---

Purpose

Tell the operator when something needs their attention — and tell household members when the thing they asked for has arrived.

Those two are almost opposite requirements, and conflating them is what ruins notification systems. The operator wants silence to mean healthy; a channel carrying forty “download complete” messages a day gets muted within a week, and takes “your VPN is leaking” down with it.

Behaviour

Division of labour: lemonfiber alerts, services notify

lemonfiber does not reimplement what the stack already does well. Seerr already notifies a requester when their request is approved and when it becomes available; the *arrs have their own connection systems.

The two in the last row are the operator’s own business rather than the requester’s: somebody in the house asked for something the operator decides on, or answered the operator’s invitation. They go to the operator’s phone and to nobody else; the requester and the invitee are still told by the service that owns their side (ADR-0047).

lemonfiber’s unique contribution is the conditions nothing else observes: a VPN leak, hardlink degradation, an item downloaded but never imported, a disk that will fill before the queue drains.

Appetite is chosen during setup

The wizard asks once, offering three presets rather than a checklist:

Every individual event remains configurable afterwards through reconfiguration. The preset sets the starting point; it is not a ceiling.

Event catalogue

Delivery channels

In-app is unconditional — an alert must never exist only on a channel that might be misconfigured.

Alerts are stateful, not repeated

An ongoing condition notifies once on entry and once on resolution. It does not re-fire every poll. Repetition is how alerting becomes noise, and noise is how alerts get ignored.

Every alert carries its remedy

Consistent with G4: an alert states what happened, what it means, and what to do. “VPN check failed” is a notification; “VPN tunnel dropped — torrent traffic is halted by the killswitch, no leak occurred; restart Gluetun to resume” is useful.

On the companion

Division of labour: lemonfiber alerts, services notify extends to the app as a third party that must not join in. N10-R11 forbids the companion raising alerts of its own (N10); what is configured here is the core’s, and N4-R11 is where that is settled. A phone is the device most able to interrupt someone, which is precisely why it is not given reasons of its own to.

Appetite is chosen during setup is read on this surface rather than asked again, and N10-R8 requires a preset shown with what it means and with the exceptions the operator has made. A preset name alone is not the configuration — it is the part of it that fits on one line — and an operator working out why something did or did not reach them needs the exceptions, which are where the answer usually is.

A rehearsed alert is labelled as a rehearsal on the terms N6-R1 sets, and N10-R9 additionally forbids presenting it as an alert that was sent. On a device where a test and the real thing arrive identically, that is not a subtle distinction.

Alerts that could not be read are told apart from there being none (N10-R12).

States

Per alert condition:

Edge cases

Acceptance criteria

Related

• B3 Dashboard — in-app delivery surface
• C1 Diagnostics — the checks producing most conditions
• C7 Queue health · C8 Provider health
• D4 Household request flow — Seerr’s side
• G4 Error model