SignalBeam Edge

Fleet management platform for edge devices that eliminates manual SSH access

SignalBeam Edge is a platform for onboarding, monitoring, and updating fleets of edge devices (e.g., Raspberry Pis, mini-PCs running containers) from a single dashboard. It targets small-to-medium fleets that need simple, reliable rollout and visibility without heavyweight IoT stacks.

🚀 New to SignalBeam? → Start Here: 5-Minute Quick Start Guide

Fully automated setup with zero manual configuration!

🎯 Product Focus

Radical simplicity: device → group → bundle → status
First-class fleet visibility with clear rollout outcomes
Built for teams managing ~5–200 devices without an IoT platform team
Open, opinionated stack that integrates with existing tooling

⚡ Quick Start

New to SignalBeam? Get up and running in under 5 minutes with fully automated setup:

👉 Read the Quick Start Guide 👈

The Quick Start guide includes:

✅ Zero-configuration Zitadel setup (fully automated via API)
✅ One-command backend startup with .NET Aspire
✅ Automatic frontend configuration
✅ No manual steps in Zitadel console required!

🏗️ Architecture at a Glance

Core Components

Component	Path	Description
Edge Agent	`src/EdgeAgent/`	Runs on devices, handles registration, heartbeats, bundle reconciliation, and status reporting
DeviceManager	`src/DeviceManager/`	Core API for device identity, grouping, status, and bundle assignment
BundleOrchestrator	`src/BundleOrchestrator/`	Coordinates bundle rollouts and deployment state tracking
TelemetryProcessor	`src/TelemetryProcessor/`	Ingests and processes metrics/telemetry from devices
Web UI	`web/`	React + TypeScript dashboard for fleet management

Infrastructure Stack

Database: PostgreSQL with TimescaleDB for time-series data
Cache: Valkey (Redis-compatible)
Messaging: NATS with JetStream for event streaming
Storage: Azure Blob Storage for bundle artifacts
Orchestration: .NET Aspire for local development

🚀 Detailed Setup

📘 For step-by-step instructions with automated Zitadel configuration, see QUICKSTART.md

Prerequisites

.NET 9 SDK
Docker Desktop (for infrastructure services)
Node.js 20+ (for frontend)
.NET Aspire workload:
```
dotnet workload install aspire
```

Run the Full Stack (Recommended)

The easiest way to run the entire SignalBeam platform locally:

# Navigate to the Aspire AppHost
cd src/SignalBeam.AppHost

# Start all services (automatically configures Zitadel!)
dotnet run

This will:

Start PostgreSQL, Valkey, NATS, and Azure Storage (Azurite)
Start and automatically configure Zitadel (OIDC authentication)
Launch all backend microservices
Open the Aspire Dashboard at http://localhost:15888

Aspire Dashboard provides:

Service logs and traces
Metrics visualization
Service health status
Service URLs and endpoints

Run the Frontend

After the backend is running, in a separate terminal:

# Update frontend config from auto-generated Zitadel settings
./scripts/update-frontend-config.sh

# Start the frontend
cd web
npm install  # First time only
npm run dev

The web UI will be available at http://localhost:5173

Run Individual Services

To run a single service (requires infrastructure to be running):

cd src/BundleOrchestrator/SignalBeam.BundleOrchestrator.Host
dotnet run

📖 Core Workflows (MVP)

1. Device Registration

Edge agent registers device with tenant + device ID
Device appears in the web dashboard
Agent begins sending heartbeats

2. Heartbeat & Health Monitoring

Agent sends periodic health metrics (CPU, memory, disk)
Dashboard displays online/offline status
Historical metrics stored in TimescaleDB

3. Bundle Management

Create bundles with container definitions
Version bundles for controlled releases
Assign bundles to devices or groups

4. Rollout Orchestration

User initiates rollout to target devices/groups
Real-time tracking of rollout progress
Device-level status: pending → updating → succeeded/failed
Automatic retries for failed devices
Rollout cancellation for active deployments

5. Device Reconciliation

Agent pulls desired bundle configuration
Automatically starts/stops containers to match desired state
Reports deployment status and errors back to cloud

🎨 Features

✅ Implemented (MVP)

🚧 In Progress / Planned

Advanced rollout strategies (canary, blue/green)
Device-level logs aggregation
Alert rules and notifications
RBAC for multi-user teams
Prometheus metrics export
Grafana dashboard templates
mTLS for device-to-cloud communication
Air-gapped deployment support

🛠️ Technology Stack

Backend (.NET 9)

Framework: .NET 9, C# 14, ASP.NET Core Minimal APIs
Architecture: Hexagonal (Ports & Adapters) with CQRS
Database: Entity Framework Core + PostgreSQL + TimescaleDB
Messaging: NATS with JetStream
Storage: Azure Blob Storage (Azurite locally)
Observability: OpenTelemetry, Serilog, Prometheus
Validation: FluentValidation
Testing: xUnit, FluentAssertions, Testcontainers

Frontend (React + TypeScript)

Framework: React 18, TypeScript, Vite
UI Library: shadcn/ui (Tailwind CSS-based)
State Management: TanStack Query (server state) + Zustand (client state)
Routing: React Router v6
Forms: React Hook Form + Zod
Testing: Vitest, Testing Library

Infrastructure

.NET Aspire: Local development orchestration
Docker: Containerization
PostgreSQL: Primary data store
TimescaleDB: Time-series extension for metrics
Valkey: Distributed caching
NATS: Message broker and event streaming
Azure Blob Storage: Bundle artifact storage

📚 Documentation

Getting Started

Quick Start Guide - 5-minute automated setup (recommended for first-time users)
Project Overview - High-level architecture and workflows
Running with Aspire - Local development with .NET Aspire
Docker Requirements - Docker setup guide

Architecture

Domain Model - DDD entities and aggregates
Technical Architecture - Detailed system design
API Documentation - REST API reference

Features

Rollout Management - Bundle deployment and tracking
Device Management - Device lifecycle and grouping

Development

Local Development Guide - Comprehensive setup guide
Contributing Guidelines - How to contribute
Code Style - Coding conventions

Operations

Deployment Guide - Production deployment
Monitoring - Observability and metrics

🧪 Testing

Run All Tests

dotnet test

Run Unit Tests Only

dotnet test --filter Category!=Integration

Run Integration Tests

# Requires Docker for Testcontainers
dotnet test --filter Category=Integration

Frontend Tests

cd web
npm test

🔐 Security

Authentication & Authorization

Devices: API key authentication
Users: JWT-based authentication (OIDC-ready)
API Gateway: Rate limiting per tenant
Production: Support for Azure AD, Zitadel, or any OIDC provider

Best Practices

API keys rotatable per device
JWT tokens with short expiration
HTTPS enforced in production
Secrets managed via Azure Key Vault or environment variables

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

Development workflow
Code review process
Testing requirements
Documentation standards

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

Built with .NET 9 and .NET Aspire
UI components from shadcn/ui
Inspired by the need for simple, effective edge device management

📞 Support

Documentation: docs/
Issues: GitHub Issues
Discussions: GitHub Discussions

Name	create-issues
Description	Create multiple GitHub issues from a PRD or feature plan, with an epic issue linking all tasks

create-issues

SKILL.md