Incident Management
Relevant source files
The following files were used as context for generating this wiki page:
Incident Management in StatusBeam provides a structured framework for tracking, updating, and displaying service disruptions and their resolutions. It utilizes a lifecycle-based approach where incidents progress through specific states, providing transparency to users through a reverse-chronological timeline on the status page and distributed feeds.
The system is designed to be CDN-native, with the Check Layer (Cloudflare Cron Worker) or inbound webhooks populating data into D1 and KV stores, which the Display Layer (Astro site) then renders at the edge to ensure the status page remains available even during monitored service outages.
Sources: ARCHITECTURE.md:12-25, README.md:46-77
Data Model and Lifecycle
Incidents are modeled as primary entities linked to multiple chronological updates. Each update reflects a change in the incident's lifecycle state or provides an operator message.
Incident Entities
| Entity | Description | Key Fields |
|---|---|---|
| Incident | Represents a distinct service disruption event. | id, slug, title, severity, startedAt, resolvedAt |
| IncidentUpdate | A specific entry in an incident's timeline. | id, incidentId, state, body, createdAt |
Sources: packages/core/src/incidents.ts:7-38
Lifecycle States
Incidents transition through a defined set of states. These states determine the visual indicators (badges) on the UI and the status reported in feeds.
| State | Description | UI Badge Mapping (Typical) |
|---|---|---|
investigating | Initial state; issue is being looked into. | Major Outage Styling |
identified | The cause of the issue has been found. | Partial Outage Styling |
monitoring | A fix is implemented and being observed. | Maintenance Styling |
resolved | The issue is fully mitigated. | Operational Styling |
Sources: packages/core/src/incidents.ts:5-6, apps/web/src/components/IncidentList.tsx:18-23
The following diagram illustrates the relationship between incidents and their updates:
The ER diagram shows the one-to-many relationship where a single Incident record owns multiple IncidentUpdate entries.
Sources: packages/core/src/incidents.ts:13-38
Logic and Sorting
The system employs specific pure functions within the domain layer to determine the active status and ordering of incidents for various consumers (UI, Feeds, APIs).
State Derivation
- Active Status: An incident is considered "active" if
resolvedAtis null AND the latest state is notresolved. - Latest State: Determined by the
stateof the most recent update. If no updates exist, it falls back toresolvedifresolvedAtis present, otherwiseinvestigating.
Sources: packages/core/src/incidents.ts:51-66
Sorting Mechanisms
- UI Ordering: Incidents are grouped by active vs. resolved. Within these groups, they are sorted by recency using
resolvedAt ?? startedAt. - Feed Ordering: For RSS and Atom feeds, incidents are sorted by the "most recent activity," which considers the latest update's
createdAt, falling back toresolvedAtand thenstartedAt.
Sources: apps/web/src/components/IncidentList.tsx:26-30, packages/core/src/feed.ts:101-107
This flowchart illustrates the fallback logic used to determine the "updated at" timestamp for feed sorting.
Sources: packages/core/src/feed.ts:92-107
Display and Distribution
Incidents are presented to users via a React-based component and distributed through XML-based feeds.
Incident Timeline UI
The IncidentList component renders a reverse-chronological feed. It uses "Astro React islands" for interactivity where needed but renders to static HTML at the edge with zero JS by default.
- Active Incidents: Surfaced at the top of the list.
- Recently Resolved: Displayed below a muted divider.
- Localization: Relative times (e.g., "5m ago") are computed at edge render using locale-aware dictionaries (
en,zh,ja,ko).
Sources: apps/web/src/components/IncidentList.tsx:75-104, packages/core/src/incidents.ts:68-112
Feed Generation
The system generates Atom 1.0 and RSS 2.0 feeds containing the incident history.
- HTML Content: Incident updates are rendered as an HTML blob within the feed's
<content type="html">or<description>tags. - Stability: Uses stable, globally-unique
tag:URIs (e.g.,tag:host,2005:Incident/id) to ensure feed readers can track entries consistently.
Sources: packages/core/src/feed.ts:121-182
The sequence diagram shows the flow from data ingestion to edge rendering and cache invalidation.
Sources: ARCHITECTURE.md:68-87, README.md:52-77
Summary
The Incident Management system in StatusBeam is a decoupled, edge-optimized module that ensures high availability and accuracy. By utilizing a shared core of pure functions for state derivation and sorting, it maintains consistency across the web UI, JSON APIs, and syndication feeds. The separation between data ingestion (Worker) and presentation (Astro) allows the system to survive the very outages it is designed to report.
Sources: ARCHITECTURE.md:8-11, README.md:21-35