# FlareWatch

FlareWatch checks websites and background jobs from Cloudflare Workers and shows the results on one status page. One person runs it. Everyone else only reads it.

## People

**Operator**:
Someone who signs in and can change maintenance windows and announcements. Only an operator can copy a heartbeat's ping URL.

The person who deploys FlareWatch is an operator, through the password or a provider.
_Avoid_: Admin, user, owner

**Member**:
Someone who signs in to see more than visitors do, and changes nothing. A member sees every monitor, or, as part of an audience, the public monitors plus some page groups.
_Avoid_: Viewer, user, guest

**Audience**:
A named set of members who see the public monitors plus the monitors in certain page groups. Set in `access.ts`.
_Avoid_: Tenant, client, team

**Visitor**:
Anyone reading the status page without signing in.
_Avoid_: Public user, guest, customer

## Pages

**Status page**:
The site the status-page worker serves: the dashboard, History and monitor pages. Operators and visitors see the same routes. Operators see more.

_Avoid_: Public page, frontend

**Signed-in mode**:
The status page as an operator or member sees it: more monitors, and for the operator, operator details on each card and maintenance editing on History.
_Avoid_: Admin page, admin panel, dashboard mode

**Visitor view**:
A switch that shows someone signed in the status page exactly as a visitor sees it.
_Avoid_: Preview, public preview

**Private-only**:
A deployment where visitors get the sign-in page and nothing else. Set in config (`statusPage.visibility: 'private'`), not at runtime.
_Avoid_: Private mode, locked mode

## Monitors

**Monitor**:
One thing FlareWatch watches. It is either a check monitor or a heartbeat monitor.

**Check monitor**:
A monitor that the worker probes on a schedule: HTTP, TCP, DNS or domain expiry.
_Avoid_: Pull monitor, web monitor, endpoint

**Heartbeat monitor**:
A monitor for a scheduled job. The job reports in with a ping to FlareWatch. Silence past the grace period means down.
_Avoid_: Cron monitor, push monitor, job monitor

**Ping**:
One request a job sends to its heartbeat monitor's ping URL (start, success or fail).
_Avoid_: Check-in, beat

**Published monitor**:
A monitor visitors can see. Monitors are published unless marked private.
_Avoid_: Public monitor

**Private monitor**:
A monitor only operators and members see, or an audience whose page group holds it. It is still checked, and it never appears in visitor responses: pages, API, badges or embeds.
_Avoid_: Hidden monitor, internal monitor

**Degraded**:
What the page shows for a check monitor slower than its `maxLatencyMs`, a monitor with an expiry warning, or a heartbeat monitor that is late. It opens no incident and leaves uptime unchanged. Only expiry warnings send an alert.
_Avoid_: Slow, warning, yellow

**Confirmation**:
A vote among one to five other places, set by `confirmVia`, after the check fails, and after the `checkProxyFallback` check fails too when one is set. The failed check counts as one down vote. The monitor is down when down votes exceed half of all votes, or when fewer confirmers answer than `confirmQuorum` asks. A down result keeps the primary error.
_Avoid_: Retry, re-check

**Check now**:
An operator action that runs one check monitor's check at once and shows the result. Nothing is recorded.
_Avoid_: Manual check, test run

**Check run**:
One scheduled pass over every configured monitor, once a minute.

**Run budget**:
The deadline and spare subrequests one check run shares. A fallback, a confirmation or an extra Globalping poll runs only while some are left.

## Alerts

**Alert routing**:
The monitor IDs a webhook gets alerts for, set by its `monitors`. Without it, the webhook gets every monitor's alerts.

**Alert claim**:
A check run's temporary right to send an incident's down alert, so an overlapping run does not send it too.

**Reminder**:
A repeat of a down alert while the monitor stays down, every `reminderEveryChecks` check runs. Per monitor, off by default.
_Avoid_: Resend, nag, escalation

## History

**History**:
The page that lists incidents and maintenance windows by month, at `/history`.
_Avoid_: Events page, timeline

**Maintenance window**:
A planned period, with start, end and affected monitors, that the operator adds on History. It can repeat daily, weekly or monthly in a chosen time zone. Each run is an occurrence.
_Avoid_: Maintenance event, scheduled maintenance

**Announcement**:
A notice with a title, body and optional end time that the operator posts on History. Active announcements appear on the dashboard.

**Incident**:
A stretch of downtime FlareWatch recorded for a monitor. A failure within 15 minutes after a recovery reopens the incident, and a reopened incident ends only after 15 minutes up. The up minutes between count as downtime.
_Avoid_: Outage, event

## Storage

**Hub**:
The Durable Object in the monitor Worker that stores incidents, latency samples, heartbeat pings, maintenance windows and announcements. The status page reads it through the monitor Worker.
_Avoid_: State, KV state, database

**Lifecycle**:
The states one thing moves through, such as an incident, a down alert or a subscriber batch. Each lifecycle has a state enum and a step function in `services/worker/src/hub`.
_Avoid_: Status flag, phase

**Step function**:
The pure function that takes a lifecycle's state and an event and returns the next state. The hub writes what it returns.
_Avoid_: Handler, reducer (on the worker)