Astro Edge Frontend
Relevant source files
The following files were used as context for generating this wiki page:
The Astro Edge Frontend is the display layer of the StatusBeam project, responsible for rendering a fast, resilient status page entirely at the edge using Cloudflare Workers. It acts as a read-only consumer of time-series data and service snapshots generated by the system's worker layer.
This module is built using Astro 7, utilizing server-side rendering (SSR) to ensure the visitor's browser never needs to call third-party APIs directly. By rendering at the edge, it eliminates client-side rate limits and ensures the status page remains accessible even during service outages.
Sources: ARCHITECTURE.md:14-17, README.md:17-21, README.md:88-91
Architectural Overview
The frontend architecture is designed for "CDN-native" performance. It uses the @astrojs/cloudflare adapter to deploy as a Cloudflare Worker. The system is configuration-independent at build time; user-specific configurations (like D1/KV IDs and custom domains) are injected during the deployment process via environment variables or a per-user wrangler.jsonc.
Sources: apps/web/astro.config.ts:10-14, ARCHITECTURE.md:28-30
Core Components and Technologies
The display layer integrates several modern web technologies to balance static performance with interactive features.
| Technology | Purpose | Implementation Detail |
|---|---|---|
| Astro 7 | Core Framework | Configured with output: 'server' for edge SSR. |
| React 19 | Interactivity | Used via Astro "islands" for charts and interactive filters. |
| shadcn/ui | UI Components | Provides themed, accessible status pills, bars, and banners. |
| Recharts | Data Visualization | Renders response-time graphs and 90-day uptime timelines. |
| Tailwind CSS | Styling | Utility-first styling with dark mode support by default. |
Sources: apps/web/package.json:44-55, README.md:88-100, README.md:120-130
Data Flow (Read Path)
The frontend follows a strict read-only pattern, retrieving data from Cloudflare edge primitives (KV and D1).
The loadStatusPage function coordinates this flow by fetching the KV summary snapshot and D1 incident history in parallel to minimize latency.
Sources: apps/web/src/lib/page.ts:18-22, ARCHITECTURE.md:92-96
Caching Strategy
StatusBeam employs an aggressive edge caching strategy to maximize performance and minimize database hits.
Workers Cache and Cache-Tags
Responses are fronted by Workers Cache using specific headers. Instead of relying solely on Time-To-Live (TTL), the frontend utilizes Cache-Tag headers. This allows the check worker to purge the frontend cache instantly when a status change is detected, rather than waiting for the cache to expire.
- Cache-Control: Set to
public, s-maxage=60, stale-while-revalidate=600. - Cache-Tag: Emits a
status-pagetag and individualstatus-site-<slug>tags for each monitored service.
Sources: apps/web/src/lib/page.ts:26-29, ARCHITECTURE.md:112-115, README.md:104-106
Internationalization (i18n)
The frontend supports multiple locales, currently including English (en), Simplified Chinese (zh), Japanese (ja), and Korean (ko).
Routing and Language Negotiation
Each locale is served from a distinct URL prefix (e.g., /en/, /ja/). This prevention of cache fragmentation is critical for edge performance. Language negotiation is handled in middleware using the following priority:
- Remembered choice (via
localecookie). - Browser
Accept-Languageheader. - Default configuration (
theme.locale).
Sources: apps/web/astro.config.ts:23-35, ARCHITECTURE.md:123-125, README.md:204-215
Public API and Badges
In addition to the HTML status page, the frontend exposes a public JSON and badge API surface at /api/*.
API Endpoints
| Endpoint | Description | Data Source |
|---|---|---|
/api/status.json | Returns the full dashboard summary including all sites. | KV Snapshot |
/api/badge.json | Provides shields.io-compatible JSON for the overall status. | KV Snapshot |
/api/badge/<slug>.json | Site-specific status badge data. | KV Snapshot |
/api/badge/<slug>/uptime.json | Site-specific uptime percentage (day/week/month). | D1/KV Aggregation |
Sources: README.md:224-245, ARCHITECTURE.md:96-97
Deployment Configuration
The frontend deployment is orchestrated through wrangler.jsonc and the Astro configuration.
Build-Time Environment
The @astrojs/cloudflare adapter is configured to use a dynamic configPath. This allows the statusbeam CLI to inject user-specific Cloudflare resource IDs at build time, facilitating package-based distribution.
// apps/web/astro.config.ts:10-18
const wranglerConfigPath = process.env.STATUSBEAM_WRANGLER_CONFIG || undefined
export default defineConfig({
output: 'server',
adapter: cloudflare({ configPath: wranglerConfigPath }),
// ...
})
Sources: apps/web/astro.config.ts:10-18, DEPLOYMENT.md:12-15
Summary
The Astro Edge Frontend provides a resilient and high-performance user interface for StatusBeam. By leveraging Cloudflare's edge primitives for both compute (Workers) and storage (KV/D1), and employing advanced caching techniques like Cache-Tag purging, it ensures that status information is delivered instantly and remains available even when the underlying services being monitored are experiencing failures.