Introduction to StatusBeam

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• ARCHITECTURE.md
• DEPLOYMENT.md
• CLAUDE.md
• status.config.example.yml
• packages/core/package.json
• apps/web/package.json

StatusBeam is an open-source, CDN-native status page generator designed as a modern successor to Upptime. It operates entirely on Cloudflare's edge platform, leveraging Workers, D1 (SQLite), KV storage, and Workers Cache to provide a resilient monitoring solution. The system is architected to ensure that status pages remain accessible even when the monitored services are experiencing outages, avoiding common pitfalls like client-side rate limits by rendering all content at the edge.

Sources: README.md:1-25, ARCHITECTURE.md:4-15, CLAUDE.md:1-5

System Architecture

StatusBeam is structured as a Bun-based Turborepo monorepo, maintaining a strict separation between domain logic and infrastructure-specific implementations. The architecture is divided into three primary layers that facilitate the check-store-render pipeline.

Architectural Layers

The following diagram illustrates the dependency flow and functional separation between the core logic and the runtime applications.

Component Breakdown

Layer	Component	Responsibility
Check	Cloudflare Worker	Probes services via Cron Triggers, derives status, and writes to D1/KV.
Store	D1 & KV	D1 stores durable time-series history; KV stores current snapshots and configuration.
Display	Astro Site	Renders the status page at the edge using aggregated data from KV/D1.
Notify	Queue/Worker	Dispatches alerts to Slack or webhooks upon detecting status changes.

Sources: README.md:75-115, ARCHITECTURE.md:18-27

Data Flow and Logic

The system follows a reactive data flow where the check worker acts as the producer and the Astro web application acts as the consumer.

The Check Pipeline

1. Trigger: A Cloudflare Cron Trigger (defaulting to every 5 minutes) executes the scheduled() handler in the check worker.
2. Configuration: The worker fetches the YAML configuration from KV (key: config) and validates it using packages/core.
3. Probing: The worker performs HTTP, TCP, or SSL checks (or mirrors external providers like Atlassian Statuspage).
4. Persistence: Results are batch-inserted into D1. The worker then aggregates this history into a SiteSummary[] snapshot written to KV (key: summary).
5. Invalidation: If a status change is detected, the worker triggers a purge_cache request to Cloudflare using shared Cache-Tag definitions.

Sources: ARCHITECTURE.md:85-115, DEPLOYMENT.md:5-15

Rendering Path

The Astro web application (apps/web) performs server-side rendering (SSR) at the edge. It reads the pre-aggregated snapshot from KV to minimize latency and database load. Because it uses Workers Cache with stale-while-revalidate, most requests bypass the execution of the worker entirely until the cache is purged by the Check Layer.

Configuration and Service Monitoring

StatusBeam uses a single YAML file, status.config.yml, as the primary source of truth for monitored services and system behavior.

Supported Check Types

Type	Description
http	Standard GET/POST checks; evaluates status codes and response times.
statuspage	Mirrors Atlassian Statuspage metrics by appending /api/v2/summary.json.
incidentio	Mirrors incident.io pages using Statuspage-compatible endpoints.
sentry	Ingests verdicts from Sentry Uptime monitors via webhooks or API polling.

Sources: README.md:215-250, status.config.example.yml:7-45

Configuration Example

name: Acme Status
sites:
  - name: API
    url: https://api.example.com/health
    check: http
    maxResponseTime: 2000
  - name: Claude
    url: https://status.claude.com
    check: statuspage
notifications:
  delivery: queue
  slack:
    webhookUrl: https://hooks.slack.com/...

Sources: status.config.example.yml:1-55, README.md:195-210

Public API and Integration

Every deployment exposes edge-cached API endpoints and shields.io-compatible badges. These endpoints are served from the same KV snapshot as the main page, ensuring data consistency.

• Badges: /api/badge/<slug>.json (Status), /api/badge/<slug>/uptime.json (Uptime).
• Status API: /api/status.json provides a full rollup of the dashboard.
• Feeds: Supports RSS and Atom feeds for incident history (e.g., /feed.rss, /feed.atom).

Sources: README.md:275-310, ARCHITECTURE.md:144-148, DEPLOYMENT.md:80-90

Technical Invariants

• Configuration-Independent Builds: No user services are compiled into the binary. Configuration is loaded from KV at runtime, enabling package-based distribution where the app is a versioned dependency.
• Edge-Only Rendering: The visitor's browser never makes third-party API calls; all data aggregation happens on the server/edge side.
• Framework-Free Core: packages/core must not import Astro, React, or Cloudflare-specific types to maintain portability and testability.

Sources: ARCHITECTURE.md:120-145, DEPLOYMENT.md:5-10