Spooled Dashboard

A modern, real-time dashboard for managing job queues, workflows, and workers in the Spooled Cloud system.

Features

• Real-time Dashboard - Live KPIs, job statistics, and system health
• Jobs Management - Create, monitor, retry, cancel jobs; set priority levels
• Queue Management - Configure queues, pause/resume, view stats, set rate limits
• Worker Monitoring - Track worker status, performance, and job distribution
• Workflows - Create DAG workflows with job dependencies (visual dependency graph)
• Schedules - Cron-based recurring jobs with timezone support (daily reports, cleanups, renewals)
• API Keys - Manage programmatic access with queue restrictions and rate limits
• Outgoing Webhooks - Configure HTTP notifications from Spooled to your URLs (Slack, Discord, custom endpoints)
• WebSocket - Live updates across the dashboard (job status, queue stats, worker activity)
• Usage Tracking - Monitor plan limits, API usage, and resource consumption
• Dead-Letter Queue - Review failed jobs, inspect errors, bulk retry or purge
• Admin Portal - Create organizations, manage plans, reset usage counters

Official SDKs

This dashboard connects to the Spooled Backend. For programmatic access, use one of the official SDKs:

SDK	Package	Status
Node.js	@spooled/sdk	✅ Production Ready
Python	spooled	✅ Production Ready
Go	github.com/spooled-cloud/spooled-sdk-go	✅ Production Ready
PHP	spooled-cloud/spooled	✅ Production Ready

See the SDKs documentation for installation and usage guides.

Real-world examples (beginner friendly)

For 5 copy/paste “real life” setups (Stripe → jobs, GitHub Actions → jobs, cron schedules, CSV import, website signup), see:

• https://github.com/spooled-cloud/spooled-backend/blob/main/docs/guides/real-world-examples.md

Tech Stack

• Astro - Fast, content-focused framework
• React - UI components
• TypeScript - Type safety
• Tailwind CSS - Styling
• Radix UI - Accessible components
• TanStack Query - Server state management
• Zustand - Client state management

Quick Start

Prerequisites

• Node.js 20.19.0 or newer
• npm (the repository uses package-lock.json)
• Spooled Backend running (see spooled-backend)

Installation

# Clone the repository
git clone https://github.com/spooled-cloud/spooled-dashboard.git
cd spooled-dashboard

# Install dependencies
npm install

# Start development server
npm run dev

The dashboard will be available at http://localhost:4321

Environment Variables

Create a .env file:

# Backend API URL
PUBLIC_API_URL=http://localhost:8080

# WebSocket URL
PUBLIC_WS_URL=ws://localhost:8080

Development

# Start dev server with hot reload
npm run dev

# Type check
npm run type-check

# Lint code
npm run lint

# Format code
npm run format

# Run tests
npm run test

# Run tests with coverage
npm run test:coverage

# Build for production
npm run build

# Preview production build
npm run preview

# Analyze bundle size
npm run analyze

Project Structure

src/
├── components/           # React components
│   ├── auth/            # Authentication (Login, AuthGuard)
│   ├── dashboard/       # Dashboard views
│   ├── jobs/            # Jobs management
│   ├── queues/          # Queues management
│   ├── workers/         # Workers management
│   ├── workflows/       # Workflows management
│   ├── schedules/       # Schedules management
│   ├── settings/        # Settings pages
│   ├── realtime/        # WebSocket components
│   ├── layout/          # Layout components
│   ├── providers/       # Context providers
│   └── ui/              # Reusable UI components
├── layouts/             # Astro layouts
├── lib/                 # Utilities and APIs
│   ├── api/             # API client modules
│   ├── constants/       # Constants and config
│   ├── types/           # TypeScript types
│   ├── utils/           # Utility functions
│   └── websocket/       # WebSocket client
├── pages/               # Astro pages (routes)
└── stores/              # Zustand stores

Docker

Build and Run

# Build the image
docker build -t spooled-dashboard .

# Run the container. The current browser bundle uses build-time/static API and
# WebSocket defaults; runtime PUBLIC_* overrides are not yet wired at startup.
docker run -p 4321:4321 spooled-dashboard

Using Docker Compose

# Production image and production Compose settings. First copy `.env.example`
# to `.env`, set `CLOUDFLARE_TUNNEL_TOKEN`, and review docs/DEPLOYMENT.md.
docker compose -f docker-compose.prod.yml up -d

# Local container build (serves the production Node build; no hot reload)
docker compose up -d --build dashboard

# For hot reload, use the Node.js development command instead:
npm run dev

Pull from GitHub Container Registry

docker pull ghcr.io/spooled-cloud/spooled-dashboard:latest

Pages Overview

Route	Description
/	Login page
/onboarding	New organization registration
/dashboard	Main dashboard with KPIs
/jobs	Jobs list and management
/jobs/[id]	Job details
/jobs/dlq	Dead-letter queue
/queues	Queues list and management
/queues/[name]	Queue details
/workers	Workers list
/workers/[id]	Worker details
/workflows	Workflows list
/workflows/[id]	Workflow details with dependency graph
/schedules	Schedules list
/schedules/[id]	Schedule details
/settings	Settings navigation
/settings/profile	User profile
/settings/organization	Organization settings (with usage)
/settings/api-keys	API keys management
/settings/billing	Subscription status and billing portal
/settings/webhooks	Webhooks configuration

Admin Routes (requires admin key)

Route	Description
/admin/login	Admin key login
/admin	Admin dashboard with platform stats
/admin/organizations	List all organizations
/admin/organizations/[id]	Organization details, API keys, usage reset
/admin/plans	View all plan tiers with limits

Authentication

The dashboard uses API key-based authentication:

1. Create organization via onboarding at /onboarding (or with admin key)
2. Login with API key at / to exchange for JWT tokens
3. The short-lived access token is persisted in localStorage by Zustand
4. The refresh token remains memory-only and can renew the access token during the current page session
5. Protected routes redirect to login if unauthenticated

Admin Portal

The admin portal requires an ADMIN_API_KEY environment variable on the backend:

1. Navigate to /admin/login
2. Enter the admin key configured on the backend
3. Access platform-wide management features

Real-time Updates

WebSocket connection provides live updates:

• Job status changes
• Queue statistics
• Worker heartbeats
• Workflow progress

The connection indicator shows status in the header.

Testing

The dashboard includes comprehensive tests:

• Unit tests for utilities and API clients
• Component tests for React components
• Integration tests for page behavior

# Run all tests
npm run test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

# UI mode
npm run test:ui

Current baseline (2026-07-14): 650 passing tests across 47 test files Run npm run test:coverage for the current coverage report rather than relying on a checked-in percentage.

Documentation

• Getting Started
• API Integration
• Deployment Guide
• Security

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run npm run lint && npm run type-check && npm run test
5. Submit a pull request

License

Apache-2.0 - see LICENSE for details.