High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
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 (SQL database), and KV (key-value store) to provide a resilient, serverless monitoring solution. The system is architected to ensure the status page remains functional even when the services it monitors are experiencing outages.
The architecture is built around three primary layers: a Check Layer for service probing, a Notify Layer for status change alerts, and a Display Layer for rendering the public-facing status page. This separation ensures that data production, notification delivery, and data visualization remain decoupled and independently scalable.
Sources: ARCHITECTURE.md:7-14, README.md:14-22, README.md:52-60
System Overview and Core Workflow
The system follows a strict "Check → Store → Render" pipeline. A Cloudflare Cron Trigger initiates the workflow periodically to assess the health of configured services.
The diagram above illustrates the end-to-end data flow from scheduled checks to the end-user's browser.
Core Workflow Steps:
- Scheduled Probing: Every 5 minutes, a Cloudflare Cron Trigger executes the check Worker.
- Data Ingestion: The Worker reads the service configuration from KV, probes each service, and writes results to D1 for historical tracking and KV for an immediate status snapshot.
- Notification & Cache Purge: If a status change is detected, the Worker sends notifications (e.g., Slack) and purges the Cloudflare edge cache using tags.
- Edge Rendering: The Astro-based status page reads the snapshot from KV and history from D1 to render response-time charts and uptime bars entirely at the edge.
Sources: ARCHITECTURE.md:16-29, README.md:65-80
Layered Architecture
StatusBeam employs a modular dependency structure where layers flow downward. packages/core serves as the foundation, containing framework-free logic used by both the worker and the web application.
| Layer | Component | Description |
|---|---|---|
| Interface | apps/web | Astro SSR pages and public JSON/badge API endpoints. |
| Interface | apps/worker | Cron scheduled() handler and webhook ingest. |
| Domain | packages/core | Zod schemas, status rollups, notify payloads, and i18n logic. |
| Infrastructure | Cloudflare | D1 (SQL), KV (Key-Value), Workers Cache, and Cron Triggers. |
Sources: ARCHITECTURE.md:36-50, README.md:88-100
Dependency Flow
This diagram shows the "downward only" dependency rule where the Interface layers depend on the Domain layer, but the Domain layer remains isolated from framework-specific types.
Sources: ARCHITECTURE.md:41-52
Data Storage and Management
StatusBeam utilizes two primary Cloudflare storage primitives to handle time-series data and state management:
- Cloudflare D1 (SQLite): Acts as the durable history store. It contains tables for
checks,incidents, andincident_updates. It is used for long-term data analysis, such as rendering 90-day uptime bars. - Cloudflare KV: Stores the "current-status" snapshot and user configuration. This provides a high-performance read path for the Astro site, ensuring that the browser never needs to call a third-party API.
Sources: ARCHITECTURE.md:21-25, ARCHITECTURE.md:76-79, README.md:104-105
Service Probing and Adapters
The system supports multiple check types to determine service health. These are defined in the packages/core/src/check.ts module and validated via Zod.
| Check Type | Functionality |
|---|---|
http | Probes URLs and derives status from codes and response times. |
statuspage | Mirrors Atlassian Statuspage verdicts via /api/v2/summary.json. |
incidentio | Mirrors incident.io status pages (Statuspage-compatible). |
sentry | Ingests Sentry Uptime monitor verdicts via webhooks. |
Sources: README.md:155-170, packages/core/src/check.test.ts:74-95
Status Derivation Logic
Service health is determined by comparing response metrics against user-defined constraints. For example, a service is marked as degraded if the response time exceeds maxResponseTime. If a status code does not match the expectedStatusCodes (default 200), the service is marked as down.
Sources: README.md:144-150, packages/core/src/check.test.ts:24-34
Cache Invalidation Strategy
To provide near-instant updates without high database load, StatusBeam utilizes tag-based cache purging.
The check worker emits a purge request to Cloudflare's purge_cache API using the CF_API_TOKEN and CF_ZONE_ID. The web application emits matching Cache-Tag headers, ensuring the edge cache is only invalidated when a status actually changes.
Sources: ARCHITECTURE.md:102-111, DEPLOYMENT.md:131-135
Conclusion
The high-level architecture of StatusBeam is optimized for resilience and performance at the edge. By leveraging Cloudflare's native primitives (D1, KV, and Workers), it eliminates the common pitfalls of client-side rate limits found in previous generations of status page generators. The strict separation of concerns—from the framework-free core to the specialized worker and display apps—provides a robust foundation for monitoring distributed services.
Sources: ARCHITECTURE.md:113-118, README.md:24-40