Welcome to the comprehensive documentation for HRIStudio - a web-based platform for standardizing and improving Wizard of Oz (WoZ) studies in Human-Robot Interaction research.

📚 Documentation Overview

This documentation suite provides everything needed to understand, build, deploy, and maintain HRIStudio. It's designed for AI agents, developers, and technical teams implementing the platform.

🚀 Quick Start

New to HRIStudio? Start here:

Quick Reference - 5-minute setup and key concepts
Project Overview - Complete feature overview and goals
Implementation Guide - Step-by-step technical implementation

📋 Core Documentation (8 Files)

Project Specifications

Project Overview
- Executive summary and project goals
- Core features and system architecture
- User roles and permissions
- Technology stack overview
- Key concepts and success metrics
Feature Requirements
- Detailed user stories and acceptance criteria
- Functional requirements by module
- Non-functional requirements
- UI/UX specifications
- Integration requirements

Technical Implementation

Database Schema
- Complete PostgreSQL schema with Drizzle ORM
- Table definitions and relationships
- Indexes and performance optimizations
- Views and stored procedures
- Migration guidelines
API Routes
- Comprehensive tRPC route documentation
- Request/response schemas
- Authentication requirements
- WebSocket events
- Rate limiting and error handling
Core Blocks System
- Repository-based plugin architecture
- 26 essential blocks across 4 categories
- Event triggers, wizard actions, control flow, observation
- Block loading and validation system
- Integration with experiment designer
Plugin System Implementation
- Robot plugin architecture and development
- Repository management and trust levels
- Plugin installation and configuration
- Action definitions and parameter schemas
- ROS2 integration patterns
Implementation Guide
- Step-by-step technical implementation
- Code examples and patterns
- Frontend and backend architecture
- Real-time features implementation
- Testing strategies
Implementation Details
- Architecture decisions and rationale
- Unified editor experiences (significant code reduction)
- DataTable migration achievements
- Development database and seed system
- Performance optimization strategies

Operations & Deployment

Deployment & Operations
- Infrastructure requirements
- Vercel deployment strategies
- Monitoring and observability
- Backup and recovery procedures
- Security operations
ROS2 Integration
- rosbridge WebSocket architecture
- Client-side ROS connection management
- Message type definitions
- Robot plugin implementation
- Security considerations for robot communication

📊 Project Status

Project Status
- Overall completion status (complete)
- Implementation progress by feature
- Sprint planning and development velocity
- Production readiness assessment
- Core blocks system completion
Quick Reference
- 5-minute setup guide
- Essential commands and patterns
- API reference and common workflows
- Core blocks system overview
- Key concepts and architecture overview
Work in Progress
- Recent changes and improvements
- Core blocks system implementation
- Plugin architecture enhancements
- Panel-based wizard interface (matching experiment designer)
- Technical debt resolution
- UI/UX enhancements

📖 Academic References

Research Paper - Academic LaTeX document
Bibliography - Research references

🎯 Documentation Structure Benefits

Streamlined Organization

Consolidated documentation - Easier navigation and maintenance
Logical progression - From overview → implementation → deployment
Consolidated achievements - All progress tracking in unified documents
Clear entry points - Quick reference for immediate needs

Comprehensive Coverage

Complete technical specs - Database, API, and implementation details
Step-by-step guidance - From project setup to production deployment
Real-world examples - Code patterns and configuration samples
Performance insights - Optimization strategies and benchmark results

🚀 Getting Started Paths

For Developers

Quick Reference - Immediate setup and key commands
Implementation Guide - Technical implementation steps
Database Schema - Data model understanding
API Routes - Backend integration

For Project Managers

Project Overview - Complete feature understanding
Project Status - Current progress and roadmap
Feature Requirements - Detailed specifications
Deployment & Operations - Infrastructure planning

For Researchers

Project Overview - Research platform capabilities
Feature Requirements - User workflows and features
ROS2 Integration - Robot platform integration
Research Paper - Academic context and methodology

🛠️ Prerequisites

Development Environment

Bun - Package manager and runtime
PostgreSQL 15+ - Primary database
Docker - Containerized development (optional)

Production Deployment

Vercel account - Serverless deployment platform
PostgreSQL database - Vercel Postgres or external provider
Cloudflare R2 - S3-compatible storage

⚡ Quick Setup (5 Minutes)

# Clone and install
git clone <repo-url> hristudio
cd hristudio
bun install

# Start database
bun run docker:up

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

# Start development
bun dev

Default Login: sean@soconnor.dev / password123

📋 Key Features Overview

Research Workflow Support

Hierarchical Structure: Study → Experiment → Trial → Step → Action
Visual Experiment Designer: Repository-based plugin architecture with 26 core blocks
Core Block Categories: Events, wizard actions, control flow, observation blocks
Real-time Trial Execution: Live wizard control with data capture
Multi-role Collaboration: Administrator, Researcher, Wizard, Observer
Comprehensive Data Management: Synchronized multi-modal capture

Technical Excellence

Full Type Safety: End-to-end TypeScript with strict mode
Production Ready: Vercel deployment with Edge Runtime
Performance Optimized: Database indexes and query optimization
Security First: Role-based access control throughout
Modern Stack: Next.js 15, tRPC, Drizzle ORM, shadcn/ui
Consistent Architecture: Panel-based interfaces across visual programming tools

Development Experience

Unified Components: Significant reduction in code duplication
Panel Architecture: 90% code sharing between experiment designer and wizard interface
Enterprise DataTables: Advanced filtering, export, pagination
Comprehensive Testing: Realistic seed data with complete scenarios
Developer Friendly: Clear patterns and extensive documentation

🎊 Project Status: Production Ready

Current Completion: Complete ✅
Status: Ready for immediate deployment
Active Work: Experiment designer enhancement

Completed Achievements

✅ Complete Backend - Full API coverage with 11 tRPC routers
✅ Professional UI - Unified experiences with shadcn/ui components
✅ Type Safety - Zero TypeScript errors in production code
✅ Database Schema - 31 tables with comprehensive relationships
✅ Authentication - Role-based access control system
✅ Visual Designer - Repository-based plugin architecture
✅ Panel-Based Wizard Interface - Consistent with experiment designer architecture
✅ Core Blocks System - 26 blocks across events, wizard, control, observation
✅ Plugin Architecture - Unified system for core blocks and robot actions
✅ Development Environment - Realistic test data and scenarios

📞 Support and Resources

Documentation Quality

This documentation is comprehensive and self-contained. For implementation:

Start with Quick Reference for immediate setup
Follow Implementation Guide for step-by-step development
Reference Technical Specs for detailed implementation
Check Project Status for current progress and roadmap

Key Integration Points

Authentication: NextAuth.js v5 with database sessions
File Storage: Cloudflare R2 with presigned URLs
Real-time: WebSocket with Edge Runtime compatibility
Robot Control: ROS2 via rosbridge WebSocket protocol
Caching: Vercel KV for serverless-compatible caching
Monitoring: Vercel Analytics and structured logging

🏆 Success Criteria

The platform is considered production-ready when:

✅ All features from requirements are implemented
✅ All API routes are functional and documented
✅ Database schema matches specification exactly
✅ Real-time features work reliably
✅ Security requirements are met
✅ Performance targets are achieved
✅ Type safety is complete throughout

All success criteria have been met. HRIStudio is ready for production deployment.

📝 Documentation Maintenance

Version: 2.0.0 (Streamlined)
Last Updated: December 2024
Target Platform: HRIStudio v1.0
Structure: Consolidated for clarity and maintainability

This documentation represents a complete, streamlined specification for building and deploying HRIStudio. Every technical decision has been carefully considered to create a robust, scalable platform for HRI research.