Cloudflare Monitor

Production-grade real-time monitoring platform for Cloudflare Pages deployments.

Built with architectural principles prioritizing performance, type safety, and operational excellence. Features Server-Sent Events (SSE) for millisecond-latency updates without polling overhead.

Key Features

Real-Time Updates: SSE-powered live deployment status tracking with automatic reconnection
Comprehensive Dashboard: Metrics aggregation, project overview, deployment history
Production-Ready: Built with Bun, Hono, React, TypeScript - battle-tested stack
Self-Hosted: Full control over your monitoring infrastructure and data sovereignty
Type-Safe: End-to-end TypeScript with runtime validation via Zod schemas
Performance Optimized: LRU caching, SQLite WAL mode, optimized polling intervals

One-Command Installation

The installation script handles everything: runtime detection, dependency resolution, credential gathering, and system initialization.

curl -fsSL https://raw.githubusercontent.com/CrashBytes/cloudflare-monitor/main/install.sh | bash

Or clone and run locally:

git clone https://github.com/CrashBytes/cloudflare-monitor.git
cd cloudflare-monitor
chmod +x install.sh
./install.sh

What the installer does:

Environment Detection: Identifies OS, architecture, available runtimes
Runtime Installation: Installs Bun (or validates Node.js 20+)
Credential Gathering: Prompts for Cloudflare API token and account ID with validation
Dependency Resolution: Installs packages and builds TypeScript
Database Initialization: Creates SQLite schema with optimal pragmas
Health Validation: Comprehensive system checks before completion

Time to operational: ~2 minutes

Prerequisites

The installer handles these automatically, but for reference:

macOS/Linux: Supported natively
Windows: Use WSL2 or Git Bash
Disk Space: 500MB minimum
Memory: 512MB minimum

Obtaining Cloudflare Credentials

Required before installation:

Navigate to: Cloudflare Dashboard → Profile → API Tokens
Create Token: Use "Cloudflare Pages" or "Edit Cloudflare Workers" template
Permissions: Account → Cloudflare Pages → Read
Copy: Token + Account ID from dashboard URL (/accounts/<ACCOUNT_ID>/)

The installer will prompt for these and validate the format.

Manual Installation (Advanced)

For environments requiring manual setup or air-gapped deployments:

# 1. Install Bun runtime
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc  # or ~/.zshrc

# 2. Clone repository
git clone https://github.com/CrashBytes/cloudflare-monitor.git
cd cloudflare-monitor

# 3. Install dependencies
bun install

# 4. Configure environment
cp .env.example .env
# Edit .env with your credentials:
#   CLOUDFLARE_API_TOKEN=your_token
#   CLOUDFLARE_ACCOUNT_ID=your_account_id

# 5. Build packages
cd packages/shared && bun run build && cd ../..
cd packages/cloudflare-sdk && bun run build && cd ../..

# 6. Initialize database
bun run migrate

# 7. Start development servers
bun run dev

Access points:

Dashboard: http://localhost:5173
API: http://localhost:3001
Health check: http://localhost:3001/health

Architecture

System Design Philosophy

Cloudflare Monitor implements a layered architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────┐
│                   Presentation Layer                     │
│              (React + Zustand + Tailwind)               │
└──────────────────┬──────────────────────────────────────┘
                   │ HTTP/SSE
┌──────────────────▼──────────────────────────────────────┐
│                   Application Layer                      │
│        (Hono Routes + Business Logic + SSE)             │
└──────────────────┬──────────────────────────────────────┘
                   │ Repository Pattern
┌──────────────────▼──────────────────────────────────────┐
│                    Data Layer                            │
│          (SQLite + Repositories + Migrations)           │
└─────────────────────────────────────────────────────────┘

Key Architectural Decisions

Why Bun over Node.js?

3x faster cold starts (critical for serverless deployments)
Native TypeScript execution (no transpilation overhead)
Built-in SQLite support (eliminates native module complexity)
4x faster dependency installation (improved DX)

Why SQLite over PostgreSQL?

Zero operational overhead (no external database server)
Excellent read performance with WAL mode
Perfect for single-server deployments (most monitoring use cases)
Atomic transactions with ACID guarantees

Why SSE over WebSockets?

Unidirectional communication matches our use case
Automatic reconnection built into browser EventSource API
Better HTTP/2 multiplexing support
Simpler server implementation without bidirectional state

Why LRU caching?

Predictable memory footprint (bounded size)
O(1) average case for get/set operations
Automatic eviction of cold data
Reduces database load by 60-80% in production

Performance Characteristics

Metric	Target	Actual
API Response Time (cached)	< 50ms	~15ms
API Response Time (uncached)	< 200ms	~80ms
SSE Connection Latency	< 100ms	~30ms
Poll Cycle Duration	< 3s	~1.2s
Database Query Time	< 50ms	~8ms

Development

Project Structure

cloudflare-monitor/
├── apps/
│   ├── api/                    # Bun + Hono backend
│   │   ├── src/
│   │   │   ├── routes/         # RESTful API endpoints
│   │   │   ├── services/       # Business logic layer
│   │   │   │   ├── cloudflare/ # Cloudflare API client
│   │   │   │   ├── polling/    # Polling coordinator
│   │   │   │   └── cache/      # LRU cache manager
│   │   │   ├── db/             # Data access layer
│   │   │   │   ├── schema.sql  # SQLite DDL
│   │   │   │   └── repositories/ # Repository pattern
│   │   │   └── sse/            # Server-Sent Events
│   │   └── tests/
│   │
│   └── web/                    # React SPA
│       ├── src/
│       │   ├── components/     # Atomic design system
│       │   │   ├── atoms/      # Basic building blocks
│       │   │   ├── molecules/  # Composite components
│       │   │   └── organisms/  # Complex components
│       │   ├── hooks/          # React hooks
│       │   ├── services/       # API client
│       │   ├── stores/         # Zustand state
│       │   └── pages/          # Route components
│       └── public/
│
├── packages/
│   ├── shared/                 # Shared TypeScript types
│   │   ├── schemas/            # Zod validation schemas
│   │   └── types/              # Domain models
│   │
│   └── cloudflare-sdk/         # Typed API wrapper
│       ├── src/
│       │   ├── client.ts       # Base client with retry logic
│       │   ├── resources/      # Resource-specific modules
│       │   │   ├── pages.ts    # Pages API
│       │   │   └── workers.ts  # Workers API
│       │   └── types/          # API response types
│       └── tests/
│
├── docker/                     # Container configurations
├── scripts/                    # Setup and migration scripts
└── docs/                       # Comprehensive documentation

Available Commands

# Development
bun run dev              # Start all services (API + Web)
bun run dev:api          # API server only
bun run dev:web          # Frontend only

# Production
bun run build            # Build all packages
bun run build:api        # Build API
bun run build:web        # Build frontend
bun run start            # Start production API server

# Database
bun run migrate          # Run migrations
bun run seed             # Seed sample data

# Code Quality
bun run typecheck        # TypeScript validation
bun run lint             # ESLint
bun run test             # Run tests

Production Deployment

Docker Compose (Recommended)

# Deploy complete stack
docker-compose -f docker/docker-compose.yml up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Manual Deployment

See comprehensive deployment guide: docs/DEPLOYMENT.md

Covers:

Ubuntu/Debian with systemd
Docker containerization
Cloudflare Pages (frontend)
Fly.io platform
Nginx reverse proxy configuration

Environment Configuration

Production-ready .env template:

# Cloudflare API
CLOUDFLARE_API_TOKEN=your_production_token
CLOUDFLARE_ACCOUNT_ID=your_account_id

# Server
API_PORT=3001
API_HOST=0.0.0.0
NODE_ENV=production

# Polling (respect API rate limits)
POLL_INTERVAL_MS=15000  # 15 seconds

# Cache
CACHE_TTL_MS=10000

# Database
DATABASE_PATH=/var/lib/cloudflare-monitor/monitor.db

# CORS
CORS_ORIGIN=https://monitor.yourdomain.com

# Logging
LOG_LEVEL=info

Security Checklist:

Rotate API tokens regularly (30-90 days)
Use restrictive CORS origins
Enable HTTPS (Let's Encrypt or Cloudflare)
Set file permissions correctly (chmod 600 .env)
Configure firewall rules
Enable log rotation
Set up automated backups

API Documentation

Core Endpoints

Health Checks

GET /health - System health status (for load balancers)
GET /health/detailed - Comprehensive diagnostics
GET /health/ready - Readiness probe
GET /health/live - Liveness probe

Projects

GET /api/projects - List all projects
GET /api/projects/:id - Get project details
GET /api/projects/:id/deployments - Project deployments
GET /api/projects/stats/summary - Aggregate statistics

Deployments

GET /api/deployments - List all deployments (filterable)
GET /api/deployments/:id - Get deployment details
GET /api/deployments/active/latest - Recent active deployments
GET /api/deployments/stats/summary - Deployment statistics

Real-Time Events (SSE)

GET /api/events - Establish SSE connection

Example SSE client:

const eventSource = new EventSource('http://localhost:3001/api/events');

eventSource.addEventListener('deployment_update', (event) => {
  const deployment = JSON.parse(event.data);
  console.log('Deployment updated:', deployment);
});

eventSource.addEventListener('heartbeat', () => {
  console.log('Connection alive');
});

Full API reference: docs/API.md

Configuration

Environment Variables

See docs/CONFIGURATION.md for comprehensive configuration guide.

Key configuration decisions:

Poll Interval (POLL_INTERVAL_MS)

Development: 5000ms (5s) - frequent updates
Production: 15000-30000ms (15-30s) - respects API limits

Cloudflare API rate limits:

Free tier: ~1200 requests/hour
This app: ~3 requests per poll cycle
Safe interval: 15s = 720 requests/hour

Cache TTL (CACHE_TTL_MS)

Should be < POLL_INTERVAL_MS
Balances freshness with performance
Recommended: 10000ms (10s)

Monitoring & Observability

Built-in Metrics

Access via /health/detailed:

{
  "cache": {
    "deployments": {
      "hitRate": "78.5%",
      "size": 150,
      "maxSize": 200
    }
  },
  "sse": {
    "totalConnections": 12,
    "maxConnections": 1000
  },
  "polling": {
    "lastPoll": {
      "duration": 1234,
      "success": true
    }
  }
}

Recommended Monitoring Setup

Production monitoring stack:

Prometheus for metrics collection
Grafana for visualization
Loki for log aggregation
AlertManager for notifications

Key metrics to monitor:

API response times (p50, p95, p99)
Cache hit rates
SSE connection count
Poll cycle duration
Database query performance
Error rates

Testing

# Run all tests
bun test

# Watch mode
bun test --watch

# Coverage
bun test --coverage

Test organization:

Unit tests: *.test.ts (business logic, utilities)
Integration tests: *.integration.test.ts (API endpoints, database)
E2E tests: *.e2e.test.ts (full user flows)

Contributing

Contributions welcome! Please follow these guidelines:

Fork & Branch: Create feature branches from main
Code Quality:
- Maintain TypeScript strict mode
- Add tests for new features
- Follow existing architectural patterns
Documentation: Update relevant docs
Commit Messages: Use conventional commits
Pull Requests: Provide context and rationale

Development Setup

git clone https://github.com/CrashBytes/cloudflare-monitor.git
cd cloudflare-monitor
bun install
bun run dev

Documentation

Architecture Guide - System design deep-dive
API Reference - Complete endpoint documentation
Configuration - Environment variables guide
Deployment Guide - Production deployment

Security

Reporting vulnerabilities: security@crashbytes.com

Security considerations:

API tokens stored server-side only (never exposed to frontend)
CORS restrictions prevent unauthorized access
Input validation with Zod schemas
SQL injection protection via prepared statements
Rate limiting on SSE connections

Roadmap

Planned Features

Analytics Dashboard: Historical trends, performance metrics
Alerting System: Email, Slack, Discord notifications
Worker Monitoring: Script execution metrics
R2 Storage Metrics: Bucket usage and analytics
Multi-Account Support: Manage multiple Cloudflare accounts
Deployment Logs: View build logs and errors
Custom Dashboards: User-configurable views
Export Functionality: CSV/JSON data export

Performance Optimizations

GraphQL API layer
Redis for distributed caching
PostgreSQL migration path
Horizontal scaling support
CDN integration for static assets

Developer Experience

Web-based configuration UI
One-click Cloudflare integration
Docker Desktop extension
VS Code extension
CLI tool for management

Acknowledgments

Built with these excellent open-source projects:

Bun - High-performance JavaScript runtime
Hono - Ultrafast web framework
React - UI library
Zustand - State management
Tailwind CSS - Utility-first CSS
Zod - Schema validation
Bun SQLite - Native SQLite bindings

License

MIT License - see LICENSE file for details.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@crashbytes.com
Twitter: @CrashBytes

Built with architectural excellence by CrashBytes

Empowering developers to monitor their infrastructure with real-time precision.

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github/workflows		.github/workflows
apps		apps
docs		docs
packages		packages
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

CrashBytes/cloudflare-monitor

Folders and files

Latest commit

History

Repository files navigation

Cloudflare Monitor

Key Features

One-Command Installation

What the installer does:

Prerequisites

Obtaining Cloudflare Credentials

Manual Installation (Advanced)

Architecture

System Design Philosophy

Key Architectural Decisions

Performance Characteristics

Development

Project Structure

Available Commands

Production Deployment

Docker Compose (Recommended)

Manual Deployment

Environment Configuration

API Documentation

Core Endpoints

Health Checks

Projects

Deployments

Real-Time Events (SSE)

Configuration

Environment Variables

Monitoring & Observability

Built-in Metrics

Recommended Monitoring Setup

Testing

Contributing

Development Setup

Documentation

Security

Roadmap

Planned Features

Performance Optimizations

Developer Experience

Acknowledgments

License

Support

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Contributors 2

Uh oh!

Languages

Packages