mirror of
https://github.com/soconnor0919/hristudio.git
synced 2025-12-11 14:44:44 -05:00
Sean O'Connor
18f709f879
• Fix repository sync implementation in admin API (was TODO placeholder) - Add full fetch/parse logic for repository.json and plugin index - Implement robot matching by name/manufacturer patterns - Handle plugin creation/updates with proper error handling - Add comprehensive TypeScript typing throughout • Fix plugin store installation state detection - Add getStudyPlugins API integration to check installed plugins - Update PluginCard component with isInstalled prop and correct button states - Fix repository name display using metadata.repositoryId mapping - Show "Installed" (disabled) vs "Install" (enabled) based on actual state • Resolve admin access and authentication issues - Add missing administrator role to user system roles table - Fix admin route access for repository management - Enable repository sync functionality in admin dashboard • Add repository metadata integration - Update plugin records with proper repositoryId references - Add metadata field to robots.plugins.list API response - Enable repository name display for all plugins from metadata • Fix TypeScript compliance across plugin system - Replace unsafe 'any' types with proper interfaces - Add type definitions for repository and plugin data structures - Use nullish coalescing operators for safer null handling - Remove unnecessary type assertions • Integrate live repository at https://repo.hristudio.com - Successfully loads 3 robot plugins (TurtleBot3 Burger/Waffle, NAO) - Complete ROS2 action definitions with parameter schemas - Trust level categorization (official, verified, community) - Platform and documentation metadata preservation • Update documentation and development workflow - Document plugin repository system in work_in_progress.md - Update quick-reference.md with repository sync examples - Add plugin installation and management guidance - Remove problematic test script with TypeScript errors BREAKING CHANGE: Plugin store now requires repository sync for robot plugins. Run repository sync in admin dashboard after deployment to populate plugin store. Closes: Plugin store repository integration Resolves: Installation state detection and repository name display Fixes: Admin authentication and TypeScript compliance issues
247 lines
9.3 KiB
Markdown
247 lines
9.3 KiB
Markdown
# HRIStudio Project Overview
|
|
|
|
## Executive Summary
|
|
|
|
HRIStudio is a web-based platform designed to standardize and improve the reproducibility of Wizard of Oz (WoZ) studies in Human-Robot Interaction (HRI) research. The platform 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.
|
|
|
|
## Project Goals
|
|
|
|
### Primary Objectives
|
|
1. **Enhance Scientific Rigor**: Standardize WoZ study methodologies to improve reproducibility
|
|
2. **Lower Barriers to Entry**: Make HRI research accessible to researchers without deep robot programming expertise
|
|
3. **Enable Collaboration**: Support multi-user workflows with role-based access control
|
|
4. **Ensure Data Integrity**: Comprehensive capture and secure storage of all experimental data
|
|
5. **Support Multiple Robot Platforms**: Provide a plugin-based architecture for robot integration
|
|
|
|
### Key Problems Addressed
|
|
- 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
|
|
|
|
### 1. Hierarchical Experiment Structure
|
|
- **Study**: Top-level container for research projects
|
|
- **Experiment**: Parameterized protocol templates within a study
|
|
- **Trial**: Executable instances of experiments with specific participants
|
|
- **Step**: Distinct phases in the execution sequence
|
|
- **Action**: Atomic tasks for wizards or robots
|
|
|
|
### 2. Visual Experiment Designer (EDE)
|
|
- Drag-and-drop interface for creating experiment workflows
|
|
- No-code solution for experiment design
|
|
- **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
|
|
- Automatic generation of robot-specific action components
|
|
- Parameter configuration with validation
|
|
- **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
|
|
|
|
### 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
|
|
- Customizable per-experiment controls
|
|
|
|
### 4. 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)
|
|
- Version tracking for reproducibility
|
|
|
|
### 5. Comprehensive Data Management
|
|
- Automatic capture of all experimental data
|
|
- Synchronized multi-modal data streams (video, audio, logs, sensor data)
|
|
- Encrypted storage for sensitive participant data
|
|
- Role-based access control for data security
|
|
- Export capabilities for analysis tools
|
|
|
|
### 6. Collaboration Features
|
|
- Multi-user support with defined roles
|
|
- Project dashboards with status tracking
|
|
- Token-based resource sharing for external collaboration
|
|
- Activity logs and audit trails
|
|
- Support for double-blind study designs
|
|
- Comment system for team communication
|
|
- File attachments for supplementary materials
|
|
|
|
## System Architecture
|
|
|
|
### Three-Layer Architecture
|
|
|
|
#### 1. User Interface Layer
|
|
- **Experiment Designer**: Visual programming interface with repository-based blocks
|
|
- **Core Blocks System**: 26 essential blocks for events, wizard actions, control flow, and observation
|
|
- **Wizard Interface**: Real-time control and monitoring during trials
|
|
- **Playback & Analysis**: Data exploration and visualization tools
|
|
- **Administration Panel**: System configuration and user management
|
|
- **Plugin Store**: Browse and install robot platform integrations
|
|
|
|
#### 2. Data Management Layer
|
|
- **Database**: PostgreSQL for structured data and metadata
|
|
- **Object Storage**: MinIO (S3-compatible) for media files
|
|
- **Access Control**: Role-based permissions system
|
|
- **API Layer**: tRPC for type-safe client-server communication
|
|
- **Data Models**: Drizzle ORM for database operations
|
|
|
|
#### 3. Robot Integration Layer
|
|
- **Plugin System**: Modular robot platform support
|
|
- **Action Translation**: Abstract to platform-specific command mapping
|
|
- **Communication Protocols**: Support for REST, ROS2, and custom protocols
|
|
- **State Management**: Robot status tracking and synchronization
|
|
|
|
## User Roles and Permissions
|
|
|
|
### Administrator
|
|
- Full system access
|
|
- User management capabilities
|
|
- System configuration
|
|
- Plugin installation and management
|
|
- Database maintenance
|
|
|
|
### Researcher
|
|
- Create and manage studies
|
|
- Design experiments
|
|
- Manage team members
|
|
- View all trial data
|
|
- Export data for analysis
|
|
|
|
### Wizard
|
|
- Execute assigned experiments
|
|
- Control robot during trials
|
|
- Make real-time decisions
|
|
- View experiment instructions
|
|
- Access quick actions
|
|
|
|
### Observer
|
|
- Read-only access to experiments
|
|
- Monitor live trial execution
|
|
- Add notes and annotations
|
|
- View historical data
|
|
- No control capabilities
|
|
|
|
## Technology Stack
|
|
|
|
### Frontend
|
|
- **Framework**: Next.js 14+ (App Router)
|
|
- **UI Components**: shadcn/ui (built on Radix UI)
|
|
- **Styling**: Tailwind CSS
|
|
- **State Management**: nuqs (URL state), React Server Components
|
|
- **Forms**: React Hook Form with Zod validation
|
|
- **Real-time**: WebSockets for live updates
|
|
|
|
### Backend
|
|
- **Runtime**: Node.js with Bun package manager
|
|
- **API**: tRPC for type-safe endpoints
|
|
- **Database**: PostgreSQL with Drizzle ORM
|
|
- **Authentication**: NextAuth.js v5 (Auth.js)
|
|
- **File Storage**: MinIO (S3-compatible object storage)
|
|
- **Background Jobs**: Bull queue with Redis
|
|
|
|
### Infrastructure
|
|
- **Containerization**: Docker and Docker Compose
|
|
- **Development**: Hot reloading, TypeScript strict mode
|
|
- **Testing**: Vitest for unit tests, Playwright for E2E
|
|
- **CI/CD**: GitHub Actions
|
|
- **Monitoring**: OpenTelemetry integration
|
|
|
|
## Key Concepts
|
|
|
|
### Experiment Lifecycle
|
|
1. **Design Phase**: Researchers create experiment templates using visual designer
|
|
2. **Configuration Phase**: Set parameters and assign team members
|
|
3. **Execution Phase**: Wizards run trials with participants
|
|
4. **Analysis Phase**: Review captured data and generate insights
|
|
5. **Sharing Phase**: Export or share experiment materials
|
|
|
|
### Data Flow
|
|
1. **Input**: Experiment designs, wizard actions, robot responses, sensor data
|
|
2. **Processing**: Action translation, state management, data synchronization
|
|
3. **Storage**: Structured data in PostgreSQL, media files in MinIO
|
|
4. **Output**: Real-time updates, analysis reports, exported datasets
|
|
|
|
### Plugin Architecture
|
|
- **Action Definitions**: Abstract representations of robot capabilities
|
|
- **Parameter Schemas**: Type-safe configuration with validation
|
|
- **Communication Adapters**: Platform-specific protocol implementations
|
|
- **Version Management**: Semantic versioning for compatibility
|
|
|
|
### Token-Based Sharing Model
|
|
- **Share Links**: Generate unique tokens for resource access
|
|
- **Permission Control**: Granular permissions (read, comment, annotate)
|
|
- **Expiration**: Time-limited access for security
|
|
- **Access Tracking**: Monitor usage and analytics
|
|
- **Public Access**: No authentication required for shared resources
|
|
- **Revocation**: Instant access removal when needed
|
|
|
|
## Development Principles
|
|
|
|
### Code Quality
|
|
- TypeScript throughout with strict type checking
|
|
- Functional programming patterns (avoid classes)
|
|
- Comprehensive error handling
|
|
- Extensive logging for debugging
|
|
- Clean architecture with separation of concerns
|
|
|
|
### User Experience
|
|
- Mobile-first responsive design
|
|
- Progressive enhancement
|
|
- Optimistic UI updates
|
|
- Comprehensive loading states
|
|
- Intuitive error messages
|
|
|
|
### Performance
|
|
- Server-side rendering where possible
|
|
- Lazy loading for non-critical components
|
|
- Image optimization (WebP, proper sizing)
|
|
- Database query optimization
|
|
- Caching strategies
|
|
|
|
### Security
|
|
- Role-based access control at all levels
|
|
- Data encryption at rest and in transit
|
|
- Input validation and sanitization
|
|
- Rate limiting on API endpoints
|
|
- Audit logging for compliance
|
|
|
|
## Success Metrics
|
|
|
|
### Technical Metrics
|
|
- Page load time < 2 seconds
|
|
- API response time < 200ms (p95)
|
|
- High uptime for critical services
|
|
- Zero data loss incidents
|
|
- Support for 100+ concurrent users
|
|
|
|
### User Success Metrics
|
|
- Time to create first experiment < 30 minutes
|
|
- High trial execution consistency
|
|
- Complete data capture
|
|
- High user satisfaction score
|
|
- Active monthly users growth
|
|
|
|
## Future Considerations
|
|
|
|
### Planned Enhancements
|
|
- AI-powered experiment design suggestions
|
|
- Advanced analytics and visualization tools
|
|
- Mobile app for wizard control
|
|
- Cloud-hosted SaaS offering
|
|
- Integration with popular analysis tools (R, Python)
|
|
|
|
### Extensibility Points
|
|
- Custom plugin development SDK
|
|
- Webhook system for external integrations
|
|
- Custom report generation
|
|
- API for third-party tools
|
|
- Theming and white-labeling support |