A comprehensive platform designed to standardize and improve the reproducibility of Wizard of Oz (WoZ) studies in Human-Robot Interaction research. HRIStudio provides researchers with standardized tools for designing experiments, executing trials, and analyzing data while ensuring reproducibility and scientific rigor.

Overview

HRIStudio addresses critical challenges in HRI research by providing a comprehensive experimental workflow management system with standardized terminology, visual experiment design tools, real-time wizard control interfaces, and comprehensive data capture capabilities.

Key Problems Solved

Lack of standardized terminology in WoZ studies
Poor documentation practices leading to unreproducible experiments
Technical barriers preventing non-programmers from conducting HRI research
Inconsistent wizard behavior across trials
Limited data capture and analysis capabilities in existing tools

Core Features

Hierarchical Structure: Study → Experiment → Trial → Step → Action
Visual Experiment Designer: Drag-and-drop protocol creation with 26+ core blocks
Plugin System: Extensible robot platform integration (RESTful, ROS2, custom)
Real-time Trial Execution: Live wizard control with comprehensive data capture
Role-Based Access: Administrator, Researcher, Wizard, Observer (4 distinct roles)
Unified Form Experiences: 73% code reduction through standardized patterns
Enterprise DataTables: Advanced filtering, pagination, export capabilities
Real-time Trial Execution: Professional wizard interface with live monitoring
Mock Robot Integration: Complete simulation system for development and testing

Quick Start

Prerequisites

Bun (package manager)
PostgreSQL 14+
Docker (recommended)

Installation

# Clone the repository
git clone <repo-url> hristudio
cd hristudio

# Install dependencies
bun install

# Start database (Docker)
bun run docker:up

# Setup database schema and seed data
bun db:push
bun db:seed

# Start development server
bun dev

Administrator: sean@soconnor.dev / password123
Researcher: alice.rodriguez@university.edu / password123
Wizard: emily.watson@lab.edu / password123
Observer: maria.santos@tech.edu / password123

Technology Stack

Framework: Next.js 15 with App Router and React 19 RC
Language: TypeScript (strict mode) - 100% type safety throughout
Database: PostgreSQL with Drizzle ORM for type-safe operations
Authentication: NextAuth.js v5 with database sessions and JWT
API: tRPC for end-to-end type-safe client-server communication
UI: Tailwind CSS + shadcn/ui (built on Radix UI primitives)
Storage: Cloudflare R2 (S3-compatible) for media files
Deployment: Vercel serverless platform with Edge Runtime
Package Manager: Bun exclusively
Real-time: WebSocket with Edge Runtime compatibility

Architecture

Core Components

1. Visual Experiment Designer

Repository-based block system with 26+ core blocks across 4 categories
Plugin architecture for both core functionality and robot actions
Context-sensitive help and best practice guidance
Core Block Categories:
- Events (4): Trial triggers, speech detection, timers, key presses
- Wizard Actions (6): Speech, gestures, object handling, rating, notes
- Control Flow (8): Loops, conditionals, parallel execution, error handling
- Observation (8): Behavioral coding, timing, recording, surveys, sensors

2. Robot Platform Integration

Unified plugin architecture for both core blocks and robot actions
Abstract action definitions with platform-specific translations
Support for RESTful APIs, ROS2, and custom protocols
Repository system for plugin distribution and management
Plugin Store with trust levels (Official, Verified, Community)

3. Adaptive Wizard Interface

Real-time experiment execution dashboard
Step-by-step guidance for consistent execution
Quick actions for unscripted interventions
Live video feed integration
Timestamped event logging

4. Comprehensive Data Management

Automatic capture of all experimental data
Synchronized multi-modal data streams
Encrypted storage for sensitive participant data
Role-based access control for data security

User Roles

Administrator: Full system access, user management, plugin installation
Researcher: Create studies, design experiments, manage teams, analyze data
Wizard: Execute trials, control robots, make real-time decisions
Observer: Read-only access, monitor trials, add annotations

Development

Available Scripts

# Development
bun dev                    # Start development server
bun build                  # Build for production
bun start                  # Start production server

# Database
bun db:push               # Push schema changes
bun db:studio             # Open database GUI
bun db:seed               # Seed with comprehensive test data
bun db:seed:simple        # Seed with minimal test data
bun db:seed:plugins       # Seed plugin repositories and plugins
bun db:seed:core-blocks   # Seed core block system

# Code Quality
bun typecheck             # TypeScript validation
bun lint                  # ESLint with autofix
bun format:check          # Prettier formatting check
bun format:write          # Apply Prettier formatting

# Docker
bun run docker:up         # Start PostgreSQL container
bun run docker:down       # Stop PostgreSQL container

Project Structure

src/
├── app/                      # Next.js App Router pages
│   ├── (auth)/              # Authentication pages
│   ├── (dashboard)/         # Main application pages
│   │   ├── studies/         # Study management
│   │   ├── experiments/     # Experiment design & designer
│   │   ├── participants/    # Participant management
│   │   ├── trials/          # Trial execution and monitoring
│   │   ├── plugins/         # Plugin management
│   │   └── admin/           # System administration
│   └── api/                 # API routes and webhooks
├── components/              # UI components
│   ├── ui/                  # shadcn/ui base components
│   ├── experiments/         # Experiment designer components
│   ├── plugins/             # Plugin management components
│   └── [entity]/            # Entity-specific components
├── server/                  # Backend code
│   ├── api/routers/         # tRPC routers (11 total)
│   ├── auth/               # NextAuth.js v5 configuration
│   └── db/                 # Database schema and setup
├── lib/                    # Utilities and configurations
└── hooks/                  # Custom React hooks

Database Schema

31 tables with comprehensive relationships:

Core Entities: users, studies, experiments, participants, trials
Execution: trial_events, steps, actions
Integration: robots, plugins, plugin_repositories
Collaboration: study_members, comments, attachments
System: roles, permissions, audit_logs

Core Concepts

Experiment Lifecycle

Design Phase: Visual experiment creation using block-based designer
Configuration Phase: Parameter setup and team assignment
Execution Phase: Real-time trial execution with wizard control
Analysis Phase: Data review and insight generation
Sharing Phase: Export and collaboration features

Plugin Architecture

Action Definitions: Abstract robot capabilities
Parameter Schemas: Type-safe configuration with validation
Communication Adapters: Platform-specific implementations
Repository System: Centralized plugin distribution

Documentation

Comprehensive documentation available in the docs/ folder:

Quick Reference: 5-minute setup guide and essential commands
Project Overview: Complete feature overview and architecture
Implementation Details: Architecture decisions and patterns
Database Schema: Complete PostgreSQL schema documentation
API Routes: Comprehensive tRPC API reference
Core Blocks System: Repository-based block architecture
Plugin System: Robot integration guide
Project Status: Current completion status (98% complete)

Research Paper

This platform is described in our research paper: "A Web-Based Wizard-of-Oz Platform for Collaborative and Reproducible Human-Robot Interaction Research"

Key contributions:

Assessment of state-of-the-art in WoZ study tools
Identification of reproducibility challenges in HRI research
Novel architectural approach with hierarchical experiment structure
Repository-based plugin system for robot integration
Comprehensive evaluation of platform effectiveness

Full paper available at: docs/paper.md

Current Status

Production Ready: Complete platform with all major features
31 Database Tables: Comprehensive data model
12 tRPC Routers: Complete API coverage
26+ Core Blocks: Repository-based experiment building blocks
4 User Roles: Complete role-based access control
Plugin System: Extensible robot integration architecture
Trial System: Unified design with real-time execution capabilities
Mock Robot Integration: Complete simulation for development and testing

Deployment

Vercel (Recommended)

# Install Vercel CLI
bun add -g vercel

# Deploy
vercel --prod

Environment Variables

DATABASE_URL=postgresql://...
NEXTAUTH_URL=https://your-domain.com
NEXTAUTH_SECRET=your-secret
CLOUDFLARE_R2_ACCOUNT_ID=...
CLOUDFLARE_R2_ACCESS_KEY_ID=...
CLOUDFLARE_R2_SECRET_ACCESS_KEY=...
CLOUDFLARE_R2_BUCKET_NAME=hristudio-files

Contributing

Read the project documentation in docs/
Follow the established patterns in .rules
Use TypeScript strict mode throughout
Implement proper error handling and loading states
Test with multiple user roles
Use bun exclusively for package management

License

[License information to be added]

Citation

If you use HRIStudio in your research, please cite our paper:

[Citation to be added once published]

HRIStudio: Advancing the reproducibility and accessibility of Human-Robot Interaction research through standardized, collaborative tools.

Languages

TypeScript 97.1%

HTML 1.8%

CSS 0.5%

Shell 0.3%

JavaScript 0.3%

README.md

HRIStudio: A Web-Based Wizard-of-Oz Platform for Human-Robot Interaction Research