# HRIStudio: A Web-Based Wizard-of-Oz Platform for Human-Robot Interaction Research 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](https://bun.sh) (package manager) - [PostgreSQL](https://postgresql.org) 14+ - [Docker](https://docker.com) (recommended) ### Installation ```bash # Clone the repository git clone 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 ``` ### Default Login Credentials - **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 ```bash # 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 1. **Design Phase**: Visual experiment creation using block-based designer 2. **Configuration Phase**: Parameter setup and team assignment 3. **Execution Phase**: Real-time trial execution with wizard control 4. **Analysis Phase**: Data review and insight generation 5. **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](docs/quick-reference.md)**: 5-minute setup guide and essential commands - **[Project Overview](docs/project-overview.md)**: Complete feature overview and architecture - **[Implementation Details](docs/implementation-details.md)**: Architecture decisions and patterns - **[Database Schema](docs/database-schema.md)**: Complete PostgreSQL schema documentation - **[API Routes](docs/api-routes.md)**: Comprehensive tRPC API reference - **[Core Blocks System](docs/core-blocks-system.md)**: Repository-based block architecture - **[Plugin System](docs/plugin-system-implementation-guide.md)**: Robot integration guide - **[Project Status](docs/project-status.md)**: 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](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) ```bash # Install Vercel CLI bun add -g vercel # Deploy vercel --prod ``` ### Environment Variables ```bash 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 1. Read the project documentation in `docs/` 2. Follow the established patterns in `.rules` 3. Use TypeScript strict mode throughout 4. Implement proper error handling and loading states 5. Test with multiple user roles 6. Use `bun` exclusively for package management ## License [License information to be added] ## Citation If you use HRIStudio in your research, please cite our paper: ```bibtex [Citation to be added once published] ``` --- **HRIStudio**: Advancing the reproducibility and accessibility of Human-Robot Interaction research through standardized, collaborative tools.