Kestrel

Real-time Visualization Platform
A powerful platform for visualizing data structures and algorithms with streaming execution and interactive playback

Features • Quick Start • Documentation • API

Overview

Kestrel is a next-generation platform for visualizing data structures and algorithms in real-time. Unlike traditional tools that execute code first and visualize later, our platform streams visualization events during execution, enabling:

Live debugging with pause, step, and continue controls
Interactive timeline with seek and checkpoint capabilities
Multi-language support for JavaScript, Python, C++, and Java
High-performance rendering using WebGL via PixiJS
Secure sandboxing with Kata Containers and Firecracker microVMs

Why Kestrel?

Feature	Traditional Tools	Kestrel
Execution Model	Batch (run then visualize)	Streaming (real-time)
Interactivity	Limited playback controls	Full timeline control
Language Support	Single language	Multi-language (JS/Python/C++/Java)
Security	Basic containerization	MicroVM isolation
Protocol	JSON	Binary Protobuf

Features

Core Capabilities

Real-time Streaming - Visualize algorithms as they execute
Interactive Controls - Play, pause, step, seek, and adjust speed
Secure Execution - Kata Containers + Firecracker microVMs
Rich Visualizations - Arrays, graphs, trees, charts, and more
Multi-language - JavaScript, Python, C++, Java
Timeline & Checkpoints - Seek to any point in execution
Persistent Sessions - Save and share visualizations

Visualization Types

Tracer	Description	Use Cases
`Array1DTracer`	One-dimensional arrays	Sorting, searching algorithms
`Array2DTracer`	Two-dimensional matrices	Dynamic programming, graph algorithms
`GraphTracer`	Graph structures	BFS, DFS, shortest path
`TreeTracer`	Tree structures	BST, heap, trie operations
`LogTracer`	Console output	Debugging, step tracking
`ChartTracer`	Statistical charts	Performance analysis
`ScatterTracer`	Scatter plots	Clustering algorithms

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Client Layer                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │   Astro      │  │   React SPA  │  │   Monaco Editor      │  │
│  │   (Static)   │──│   (/app)     │──│   + PixiJS           │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
└──────────────────────────┬──────────────────────────────────────┘
                           │ WebSocket (Binary Protobuf)
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Gateway Layer                             │
│              Rust (Axum + Tokio) WebSocket Gateway               │
│         Session Management • Rate Limiting • Routing             │
└──────────────────────────┬──────────────────────────────────────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ NATS         │  │   Redis      │  │ PostgreSQL   │
│ JetStream    │  │   (Cache)    │  │   (Metadata) │
└──────────────┘  └──────────────┘  └──────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ JS Runner    │  │ Python       │  │ C++/Java     │
│ (Browser     │  │ Runner       │  │ Runner       │
│  Worker)     │  │ (Pyodide/VM) │  │ (microVM)    │
└──────────────┘  └──────────────┘  └──────────────┘

Technology Stack

Layer	Technology	Purpose
Frontend	Astro + React 18	Static site + Interactive SPA
Editor	Monaco Editor	Code editing experience
Rendering	PixiJS	WebGL 2D rendering
Gateway	Rust (Axum)	High-performance WebSocket server
Messaging	NATS JetStream	Event streaming
Storage	PostgreSQL + Redis + S3	Data persistence
Sandboxing	Kata Containers	Secure code execution

Quick Start

Prerequisites

Node.js 20.x or higher
pnpm 8.x or higher
Docker and Docker Compose (for full stack)
Rust 1.75+ (for gateway development)

Local Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Start frontend development server
cd apps/web-astro && pnpm dev

# In another terminal, start the gateway
cd apps/gateway-rust && cargo run

Installation

Frontend Package

# Install the visualization SDK
npm install @kestrel/viz-sdk-js

# Or using pnpm
pnpm add @kestrel/viz-sdk-js

Python SDK

pip install kestrel-viz-sdk

Usage Guide

Basic JavaScript Example

import { createViz } from '@kestrel/viz-sdk-js';

// Create visualization instance
const viz = createViz((command) => {
  console.log('VizCommand:', command);
});

// Create an array tracer
const array = viz.Array1D('myArray', 'Sorting Array');

// Set initial data
array.set([64, 34, 25, 12, 22, 11, 90]);

// Perform bubble sort with visualization
for (let i = 0; i < arr.length; i++) {
  for (let j = 0; j < arr.length - i - 1; j++) {
    array.select(j, j + 1);
    
    if (arr[j] > arr[j + 1]) {
      array.swap(j, j + 1);
      [arr[j], arr[j + 1]] = [arr[j + 1], arr[j]];
    }
    
    array.deselect(j, j + 1);
  }
}

Python Example

from viz import Array1DTracer, LogTracer, setRoot, delay

# Create tracers
array = Array1DTracer('array', 'My Array')
logger = LogTracer('log', 'Console')

# Set root layout
setRoot('array')

# Initialize array
data = [64, 34, 25, 12, 22, 11, 90]
array.set(data)
logger.println(f"Initial array: {data}")

# Bubble sort with visualization
for i in range(len(data)):
    for j in range(len(data) - i - 1):
        array.select(j, j + 1)
        delay()
        
        if data[j] > data[j + 1]:
            array.swap(j, j + 1)
            data[j], data[j + 1] = data[j + 1], data[j]
            logger.println(f"Swapped: {data}")
        
        array.deselect(j, j + 1)

logger.println(f"Sorted: {data}")

API Reference

JavaScript SDK

`createViz(emit: CommandEmitter): Viz`

Creates a visualization instance.

Parameters:

emit - Function to handle visualization commands

Returns: Viz object with tracer factory methods

`Array1DTracer`

Methods for one-dimensional array visualization.

Method	Parameters	Description
`set(array)`	`number[] \| string[]`	Initialize array data
`patch(index, value?)`	`number, any?`	Update element at index
`select(start, end?)`	`number, number?`	Highlight range
`deselect(start, end?)`	`number, number?`	Remove highlight
`swap(i, j)`	`number, number`	Swap two elements

`GraphTracer`

Methods for graph visualization.

Method	Parameters	Description
`set(matrix)`	`(number \| null)[][]`	Set adjacency matrix
`addNode(id, weight?)`	`string/number, any?`	Add node
`addEdge(source, target, weight?)`	`string/number, string/number, any?`	Add edge
`visit(target, source?, weight?)`	`...`	Visit node/edge
`layoutCircle()`	-	Circular layout
`layoutTree(root?, sorted?)`	`any, boolean?`	Tree layout

Configuration

Environment Variables

Gateway

Variable	Default	Description
`RUST_LOG`	`info`	Log level
`NATS_URL`	`nats://localhost:4222`	NATS connection URL
`REDIS_URL`	`redis://localhost:6379`	Redis connection URL
`DB_URL`	-	PostgreSQL connection string
`WS_PORT`	`3001`	WebSocket server port

Runners

Variable	Default	Description
`MAX_MEMORY`	`512m`	Memory limit
`MAX_CPU`	`1.0`	CPU limit
`TIMEOUT`	`30`	Execution timeout (seconds)
`COMPILATION_TIMEOUT`	`60`	Compilation timeout (C++/Java)

Development

Project Structure

kestrel/
├── apps/
│   ├── gateway-rust/       # Rust WebSocket gateway
│   └── web-astro/          # Astro + React frontend
├── packages/
│   ├── protocol/           # Protobuf definitions
│   ├── player/             # Timeline player core
│   ├── viz-sdk-js/         # JavaScript SDK
│   └── viz-sdk-py/         # Python SDK
├── runners/
│   ├── runner-js-browser/  # Browser JS runner
│   ├── runner-python/      # Python runner
│   ├── runner-cpp/         # C++ runner
│   └── runner-java/        # Java runner
└── infra/
    ├── k8s/                # Kubernetes manifests
    └── terraform/          # AWS infrastructure

Build Commands

# Build all packages
pnpm build

# Build specific package
pnpm --filter @kestrel/web-astro build

# Development mode
pnpm dev

# Run tests
pnpm test

# Lint code
pnpm lint

Deployment

Kubernetes

# Apply manifests
kubectl apply -f infra/k8s/

# Check deployment status
kubectl get pods -n kestrel

AWS (Terraform)

cd infra/terraform
terraform init
terraform plan
terraform apply

Troubleshooting

Common Issues

Build Failures

Problem: Cannot find module '@kestrel/protocol'

Solution:

# Build protocol package first
pnpm --filter @kestrel/protocol build

# Or build all packages
pnpm build

WebSocket Connection Failed

Problem: Frontend cannot connect to gateway

Solution:

Check gateway is running
Verify port 3001 is accessible
Check firewall rules

FAQ

Q: Can I use this for production code execution?

A: While we provide strong isolation via microVMs, we recommend using this primarily for educational purposes and algorithm visualization.

Q: How do I add support for a new language?

A: See our Language Integration Guide for implementing a new runner.

Q: Can I export visualizations as videos?

A: Yes, use the recording feature in the player controls. Videos are exported as WebM or MP4.

Q: Is there a limit on execution time?

A: Default timeout is 30 seconds, configurable per runner.

License

Kestrel is licensed under the MIT License.

MIT License

Copyright (c) 2024 Kestrel

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

Made with care by the Kestrel team

Name		Name	Last commit message	Last commit date
.github		.github
.trae/documents		.trae/documents
.turbo		.turbo
apps		apps
branding		branding
docker		docker
docs		docs
infra		infra
packages		packages
public		public
runners		runners
.dockerignore		.dockerignore
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
D60FC775-B1DD-4DEC-8B77-045692DDB770.PNG		D60FC775-B1DD-4DEC-8B77-045692DDB770.PNG
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
turbo.json		turbo.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Kestrel

Table of Contents