mirror of
https://github.com/soconnor0919/hristudio.git
synced 2026-03-23 19:27:51 -04:00
docs: consolidate and archive documentation
- Move 30+ outdated docs to docs/_archive/ - Move obsolete root files to _archive/ - Update README.md (Better Auth, current features) - Update docs/README.md (new architecture diagram) - Update docs/quick-reference.md (consolidated) - Update docs/project-status.md (March 2026 state) - Update docs/nao6-quick-reference.md (14 actions, Docker services) - Update docs/implementation-guide.md (Better Auth, git submodule) - Update docs/proposal.tex (timeline updates) - Archive errors.txt, plugin_dump.json, test HTML files
This commit is contained in:
436
docs/README.md
436
docs/README.md
@@ -1,307 +1,171 @@
|
||||
# HRIStudio Documentation
|
||||
|
||||
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.
|
||||
HRIStudio is a web-based Wizard-of-Oz platform for Human-Robot Interaction research.
|
||||
|
||||
## 📚 Documentation Overview
|
||||
## Quick Links
|
||||
|
||||
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.
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| **[Quick Reference](quick-reference.md)** | Essential commands, setup, troubleshooting |
|
||||
| **[Project Status](project-status.md)** | Current development state (March 2026) |
|
||||
| **[Implementation Guide](implementation-guide.md)** | Full technical implementation |
|
||||
| **[NAO6 Integration](nao6-quick-reference.md)** | Robot setup and commands |
|
||||
|
||||
### **🚀 Quick Start**
|
||||
|
||||
**New to HRIStudio?** Start here:
|
||||
1. **[Quick Reference](./quick-reference.md)** - 5-minute setup and key concepts
|
||||
2. **[Project Overview](./project-overview.md)** - Complete feature overview and goals
|
||||
3. **[Implementation Guide](./implementation-guide.md)** - Step-by-step technical implementation
|
||||
|
||||
### **📋 Core Documentation** (8 Files)
|
||||
|
||||
#### **Project Specifications**
|
||||
1. **[Project Overview](./project-overview.md)**
|
||||
- Executive summary and project goals
|
||||
- Core features and system architecture
|
||||
- User roles and permissions
|
||||
- Technology stack overview
|
||||
- Key concepts and success metrics
|
||||
|
||||
2. **[Feature Requirements](./feature-requirements.md)**
|
||||
- Detailed user stories and acceptance criteria
|
||||
- Functional requirements by module
|
||||
- Non-functional requirements
|
||||
- UI/UX specifications
|
||||
- Integration requirements
|
||||
|
||||
#### **Technical Implementation**
|
||||
3. **[Database Schema](./database-schema.md)**
|
||||
- Complete PostgreSQL schema with Drizzle ORM
|
||||
- Table definitions and relationships
|
||||
- Indexes and performance optimizations
|
||||
- Views and stored procedures
|
||||
- Migration guidelines
|
||||
|
||||
4. **[API Routes](./api-routes.md)**
|
||||
- Comprehensive tRPC route documentation
|
||||
- Request/response schemas
|
||||
- Authentication requirements
|
||||
- WebSocket events
|
||||
- Rate limiting and error handling
|
||||
|
||||
5. **[Core Blocks System](./core-blocks-system.md)**
|
||||
- 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
|
||||
|
||||
6. **[Plugin System Implementation](./plugin-system-implementation-guide.md)**
|
||||
- Robot plugin architecture and development
|
||||
- Repository management and trust levels
|
||||
- Plugin installation and configuration
|
||||
- Action definitions and parameter schemas
|
||||
- ROS2 integration patterns
|
||||
|
||||
7. **[Implementation Guide](./implementation-guide.md)**
|
||||
- Step-by-step technical implementation
|
||||
- Code examples and patterns
|
||||
- Frontend and backend architecture
|
||||
- Real-time features implementation
|
||||
- Testing strategies
|
||||
|
||||
8. **[Implementation Details](./implementation-details.md)**
|
||||
- Architecture decisions and rationale
|
||||
- Unified editor experiences (significant code reduction)
|
||||
- DataTable migration achievements
|
||||
- Development database and seed system
|
||||
- Performance optimization strategies
|
||||
|
||||
#### **Operations & Deployment**
|
||||
9. **[Deployment & Operations](./deployment-operations.md)**
|
||||
- Infrastructure requirements
|
||||
- Vercel deployment strategies
|
||||
- Monitoring and observability
|
||||
- Backup and recovery procedures
|
||||
- Security operations
|
||||
|
||||
10. **[ROS2 Integration](./ros2-integration.md)**
|
||||
- rosbridge WebSocket architecture
|
||||
- Client-side ROS connection management
|
||||
- Message type definitions
|
||||
- Robot plugin implementation
|
||||
- Security considerations for robot communication
|
||||
|
||||
### **📊 Project Status**
|
||||
|
||||
11. **[Project Status](./project-status.md)**
|
||||
- Overall completion status (complete)
|
||||
- Implementation progress by feature
|
||||
- Sprint planning and development velocity
|
||||
- Production readiness assessment
|
||||
- Core blocks system completion
|
||||
|
||||
12. **[Quick Reference](./quick-reference.md)**
|
||||
- 5-minute setup guide
|
||||
- Essential commands and patterns
|
||||
- API reference and common workflows
|
||||
- Core blocks system overview
|
||||
- Key concepts and architecture overview
|
||||
|
||||
13. **[Work in Progress](./work_in_progress.md)**
|
||||
- Recent changes and improvements
|
||||
- Core blocks system implementation
|
||||
- Plugin architecture enhancements
|
||||
- Panel-based wizard interface (matching experiment designer)
|
||||
- Technical debt resolution
|
||||
- UI/UX enhancements
|
||||
|
||||
### **🤖 Robot Integration Guides**
|
||||
|
||||
14. **[NAO6 Complete Integration Guide](./nao6-integration-complete-guide.md)** - Comprehensive NAO6 setup, troubleshooting, and production deployment
|
||||
15. **[NAO6 Quick Reference](./nao6-quick-reference.md)** - Essential commands and troubleshooting for NAO6 integration
|
||||
16. **[NAO6 ROS2 Setup](./nao6-ros2-setup.md)** - Basic NAO6 ROS2 driver installation guide
|
||||
|
||||
### **📖 Academic References**
|
||||
|
||||
17. **[Research Paper](./root.tex)** - Academic LaTeX document
|
||||
18. **[Bibliography](./refs.bib)** - 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**
|
||||
1. **[Quick Reference](./quick-reference.md)** - Immediate setup and key commands
|
||||
2. **[Implementation Guide](./implementation-guide.md)** - Technical implementation steps
|
||||
3. **[Database Schema](./database-schema.md)** - Data model understanding
|
||||
4. **[API Routes](./api-routes.md)** - Backend integration
|
||||
|
||||
### **For Project Managers**
|
||||
1. **[Project Overview](./project-overview.md)** - Complete feature understanding
|
||||
2. **[Project Status](./project-status.md)** - Current progress and roadmap
|
||||
3. **[Feature Requirements](./feature-requirements.md)** - Detailed specifications
|
||||
4. **[Deployment & Operations](./deployment-operations.md)** - Infrastructure planning
|
||||
|
||||
### **For Researchers**
|
||||
1. **[Project Overview](./project-overview.md)** - Research platform capabilities
|
||||
2. **[Feature Requirements](./feature-requirements.md)** - User workflows and features
|
||||
3. **[NAO6 Quick Reference](./nao6-quick-reference.md)** - Essential NAO6 robot control commands
|
||||
4. **[ROS2 Integration](./ros2-integration.md)** - Robot platform integration
|
||||
5. **[Research Paper](./root.tex)** - Academic context and methodology
|
||||
|
||||
### **For Robot Integration**
|
||||
1. **[NAO6 Complete Integration Guide](./nao6-integration-complete-guide.md)** - Full NAO6 setup and troubleshooting
|
||||
2. **[NAO6 Quick Reference](./nao6-quick-reference.md)** - Essential commands and quick fixes
|
||||
3. **[ROS2 Integration](./ros2-integration.md)** - General robot integration patterns
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ **Prerequisites**
|
||||
|
||||
### **Development Environment**
|
||||
- **[Bun](https://bun.sh)** - Package manager and runtime
|
||||
- **[PostgreSQL](https://postgresql.org)** 15+ - Primary database
|
||||
- **[Docker](https://docker.com)** - Containerized development (optional)
|
||||
|
||||
### **Production Deployment**
|
||||
- **[Vercel](https://vercel.com)** account - Serverless deployment platform
|
||||
- **PostgreSQL** database - Vercel Postgres or external provider
|
||||
- **[Cloudflare R2](https://cloudflare.com/products/r2/)** - S3-compatible storage
|
||||
|
||||
---
|
||||
|
||||
## ⚡ **Quick Setup (5 Minutes)**
|
||||
## Getting Started
|
||||
|
||||
### 1. Clone & Install
|
||||
```bash
|
||||
# Clone and install
|
||||
git clone <repo-url> hristudio
|
||||
git clone https://github.com/soconnor0919/hristudio.git
|
||||
cd hristudio
|
||||
git submodule update --init --recursive
|
||||
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`
|
||||
### 2. Start Database
|
||||
```bash
|
||||
bun run docker:up
|
||||
bun db:push
|
||||
bun db:seed
|
||||
```
|
||||
|
||||
---
|
||||
### 3. Start Application
|
||||
```bash
|
||||
bun dev
|
||||
# Visit http://localhost:3000
|
||||
# Login: sean@soconnor.dev / password123
|
||||
```
|
||||
|
||||
## 📋 **Key Features Overview**
|
||||
### 4. Start NAO6 Robot (optional)
|
||||
```bash
|
||||
cd ~/Documents/Projects/nao6-hristudio-integration
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Current Architecture
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ HRIStudio Platform │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ UI Layer (Next.js + React + shadcn/ui) │
|
||||
│ ├── Experiment Designer (drag-and-drop) │
|
||||
│ ├── Wizard Interface (real-time trial execution) │
|
||||
│ └── Observer/Participant Views │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ Logic Layer (tRPC + Better Auth) │
|
||||
│ ├── 12 tRPC routers (studies, experiments, trials...) │
|
||||
│ ├── Role-based authentication (4 roles) │
|
||||
│ └── WebSocket for real-time updates │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ Data Layer (PostgreSQL + Drizzle ORM) │
|
||||
│ ├── 31 tables with complete relationships │
|
||||
│ ├── Plugin system with identifier-based lookup │
|
||||
│ └── Comprehensive event logging │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ Robot Integration (ROS2 via WebSocket) │
|
||||
│ Docker: nao_driver, ros_bridge, ros_api │
|
||||
│ Plugin identifier: "nao6-ros2" │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Key Features
|
||||
|
||||
### **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
|
||||
- **Visual Designer**: 26+ core blocks (events, wizard actions, control flow, observation)
|
||||
- **Conditional Branching**: Wizard choices with convergence paths
|
||||
- **WebSocket Real-time**: Trial updates with auto-reconnect
|
||||
- **Plugin System**: Robot-agnostic via identifier lookup
|
||||
- **Docker NAO6**: Three-service ROS2 integration
|
||||
|
||||
### **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
|
||||
## System Components
|
||||
|
||||
### **Development Experience**
|
||||
- **Unified Components**: Significant reduction in code duplication
|
||||
- **Panel Architecture**: 90% code sharing between experiment designer and wizard interface
|
||||
- **Consolidated Wizard**: 3-panel design with trial controls, horizontal timeline, and unified robot controls
|
||||
- **Enterprise DataTables**: Advanced filtering, export, pagination
|
||||
- **Comprehensive Testing**: Realistic seed data with complete scenarios
|
||||
- **Developer Friendly**: Clear patterns and extensive documentation
|
||||
### Backend (src/server/)
|
||||
- `api/routers/` - 12 tRPC routers
|
||||
- `db/schema.ts` - Drizzle schema (31 tables)
|
||||
- `services/trial-execution.ts` - Trial execution engine
|
||||
- `services/websocket-manager.ts` - Real-time connections
|
||||
|
||||
### **Robot Integration**
|
||||
- **NAO6 Full Support**: Complete ROS2 integration with movement, speech, and sensor control
|
||||
- **Real-time Control**: WebSocket-based robot control through web interface
|
||||
- **Safety Features**: Emergency stops, movement limits, and comprehensive monitoring
|
||||
- **Production Ready**: Tested with NAO V6.0 / NAOqi 2.8.7.4 / ROS2 Humble
|
||||
- **Troubleshooting Guides**: Complete documentation for setup and problem resolution
|
||||
### Frontend (src/)
|
||||
- `app/` - Next.js App Router pages
|
||||
- `components/trials/wizard/` - Wizard interface
|
||||
- `hooks/useWebSocket.ts` - Real-time trial updates
|
||||
- `lib/ros/wizard-ros-service.ts` - Robot control
|
||||
|
||||
## Plugin Identifier System
|
||||
|
||||
```typescript
|
||||
// Plugins table has:
|
||||
// - identifier: "nao6-ros2" (unique, machine-readable)
|
||||
// - name: "NAO6 Robot (ROS2 Integration)" (display)
|
||||
|
||||
// Lookup order in trial execution:
|
||||
1. Look up by identifier (e.g., "nao6-ros2")
|
||||
2. Fall back to name (e.g., "NAO6 Robot")
|
||||
3. Return null if not found
|
||||
```
|
||||
|
||||
## Branching Flow
|
||||
|
||||
```
|
||||
Step 3 (Comprehension Check)
|
||||
└── wizard_wait_for_response
|
||||
├── "Correct" → nextStepId = step4a.id
|
||||
└── "Incorrect" → nextStepId = step4b.id
|
||||
|
||||
Step 4a/4b (Branch A/B)
|
||||
└── conditions.nextStepId: step5.id → converge
|
||||
|
||||
Step 5 (Story Continues)
|
||||
└── Linear progression to conclusion
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
```bash
|
||||
# Make changes
|
||||
# ...
|
||||
|
||||
# Validate
|
||||
bun typecheck
|
||||
bun lint
|
||||
|
||||
# Push schema (if changed)
|
||||
bun db:push
|
||||
|
||||
# Reseed (if data changed)
|
||||
bun db:seed
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Build errors | `rm -rf .next && bun build` |
|
||||
| DB issues | `bun db:push --force && bun db:seed` |
|
||||
| Type errors | Check `bun typecheck` output |
|
||||
| WebSocket fails | Verify port 3001 available |
|
||||
|
||||
## External Resources
|
||||
|
||||
- [Thesis (honors-thesis)](https://github.com/soconnor0919/honors-thesis)
|
||||
- [NAO6 Integration](https://github.com/soconnor0919/nao6-hristudio-integration)
|
||||
- [Robot Plugins](https://github.com/soconnor0919/robot-plugins)
|
||||
|
||||
## File Index
|
||||
|
||||
### Primary Documentation
|
||||
- `README.md` - Project overview
|
||||
- `docs/README.md` - This file
|
||||
- `docs/quick-reference.md` - Commands & setup
|
||||
- `docs/nao6-quick-reference.md` - NAO6 commands
|
||||
|
||||
### Technical Documentation
|
||||
- `docs/implementation-guide.md` - Full technical implementation
|
||||
- `docs/project-status.md` - Development status
|
||||
|
||||
### Archive (Historical)
|
||||
- `docs/_archive/` - Old documentation (outdated but preserved)
|
||||
|
||||
---
|
||||
|
||||
## 🎊 **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
|
||||
- ✅ **Consolidated Wizard Interface** - 3-panel design with horizontal timeline and unified robot controls
|
||||
- ✅ **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
|
||||
- ✅ **NAO6 Robot Integration** - Full ROS2 integration with comprehensive control and monitoring
|
||||
- ✅ **Intelligent Control Flow** - Loops with implicit approval, branching, parallel execution
|
||||
|
||||
---
|
||||
|
||||
## 📞 **Support and Resources**
|
||||
|
||||
### **Documentation Quality**
|
||||
This documentation is comprehensive and self-contained. For implementation:
|
||||
1. **Start with Quick Reference** for immediate setup
|
||||
2. **Follow Implementation Guide** for step-by-step development
|
||||
3. **Reference Technical Specs** for detailed implementation
|
||||
4. **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 with full NAO6 robot integration support.**
|
||||
|
||||
---
|
||||
|
||||
## 📝 **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.
|
||||
**Last Updated**: March 22, 2026
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## Overview
|
||||
|
||||
This guide provides step-by-step technical instructions for implementing HRIStudio using the T3 stack with Next.js, tRPC, Drizzle ORM, NextAuth.js v5, and supporting infrastructure.
|
||||
This guide provides step-by-step technical instructions for implementing HRIStudio using the T3 stack with Next.js, tRPC, Drizzle ORM, Better Auth, and supporting infrastructure.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
@@ -25,7 +25,14 @@ This guide provides step-by-step technical instructions for implementing HRIStud
|
||||
### 1. Initialize Project
|
||||
|
||||
```bash
|
||||
# Create new Next.js project with T3 stack
|
||||
# Clone repository (includes robot-plugins as submodule)
|
||||
git clone https://github.com/soconnor0919/hristudio.git
|
||||
cd hristudio
|
||||
|
||||
# Initialize submodules
|
||||
git submodule update --init --recursive
|
||||
|
||||
# Or create from scratch with T3 stack:
|
||||
bunx create-t3-app@latest hristudio \
|
||||
--nextjs \
|
||||
--tailwind \
|
||||
|
||||
@@ -27,10 +27,15 @@ bun dev
|
||||
|
||||
| Service | Port | Description |
|
||||
|---------|------|-------------|
|
||||
| nao_driver | - | NAOqi driver node |
|
||||
| nao_driver | - | NAOqi driver + robot init |
|
||||
| ros_bridge | 9090 | WebSocket bridge |
|
||||
| ros_api | - | ROS API services |
|
||||
|
||||
**Auto-initialization**: On Docker startup, `init_robot.sh` runs automatically via SSH to:
|
||||
- Wake up the robot (`ALMotion.wakeUp`)
|
||||
- Disable autonomous life (`ALAutonomousLife.setState disabled`)
|
||||
- Ensure robot is ready for commands
|
||||
|
||||
## ROS Topics
|
||||
|
||||
**Commands (Publish to these):**
|
||||
@@ -52,6 +57,21 @@ bun dev
|
||||
/info - Robot info
|
||||
```
|
||||
|
||||
## Robot Actions (HRIStudio)
|
||||
|
||||
When actions are triggered via the wizard interface, they publish to these topics:
|
||||
|
||||
| Action | Topic | Message Type |
|
||||
|--------|-------|--------------|
|
||||
| say | `/speech` | `std_msgs/String` |
|
||||
| say_with_emotion | `/speech` | `std_msgs/String` (with NAOqi markup) |
|
||||
| wave_goodbye | `/speech` | `std_msgs/String` + gesture |
|
||||
| walk | `/cmd_vel` | `geometry_msgs/Twist` |
|
||||
| turn | `/cmd_vel` | `geometry_msgs/Twist` |
|
||||
| move_to_posture | `/service/robot_pose` | `naoqi_bridge_msgs/SetRobotPose` |
|
||||
| play_animation | `/animation` | `std_msgs/String` |
|
||||
| set_eye_leds | `/leds/eyes` | `std_msgs/ColorRGBA` |
|
||||
|
||||
## Manual Control
|
||||
|
||||
### Test Connectivity
|
||||
|
||||
@@ -1,402 +1,189 @@
|
||||
# HRIStudio Project Status
|
||||
|
||||
## 🎯 **Current Status: Production Ready**
|
||||
## Current Status: Active Development
|
||||
|
||||
**Project Version**: 1.0.0
|
||||
**Last Updated**: December 2024
|
||||
**Overall Completion**: Complete ✅
|
||||
**Status**: Ready for Production Deployment
|
||||
|
||||
### **🎉 Recent Major Achievement: Wizard Interface Multi-View Implementation Complete**
|
||||
Successfully implemented role-based trial execution interface with Wizard, Observer, and Participant views. Fixed layout issues and eliminated route duplication for clean, production-ready trial execution system.
|
||||
**Last Updated**: March 2026
|
||||
**Overall Completion**: 98%
|
||||
**Status**: Thesis research phase
|
||||
|
||||
---
|
||||
|
||||
## 📊 **Executive Summary**
|
||||
## Executive Summary
|
||||
|
||||
HRIStudio has successfully completed all major development milestones and achieved production readiness. The platform provides a comprehensive, type-safe, and user-friendly environment for conducting Wizard of Oz studies in Human-Robot Interaction research.
|
||||
HRIStudio is a complete platform for Wizard-of-Oz HRI research. Key milestones achieved:
|
||||
|
||||
### **Key Achievements**
|
||||
- ✅ **Complete Backend Infrastructure** - Full API with 12 tRPC routers
|
||||
- ✅ **Complete Frontend Implementation** - Professional UI with unified experiences
|
||||
- ✅ **Full Type Safety** - Zero TypeScript errors in production code
|
||||
- ✅ **Complete Authentication** - Role-based access control system
|
||||
- ✅ **Visual Experiment Designer** - Repository-based plugin architecture
|
||||
- ✅ **Core Blocks System** - 26 blocks across 4 categories (events, wizard, control, observation)
|
||||
- ✅ **Production Database** - 31 tables with comprehensive relationships
|
||||
- ✅ **Development Environment** - Realistic seed data and testing scenarios
|
||||
- ✅ **Trial System Overhaul** - Unified EntityView patterns with real-time execution
|
||||
- ✅ **WebSocket Integration** - Real-time updates with polling fallback
|
||||
- ✅ **Route Consolidation** - Study-scoped architecture with eliminated duplicate components
|
||||
- ✅ **Multi-View Trial Interface** - Role-based Wizard, Observer, and Participant views for thesis research
|
||||
- ✅ **Dashboard Resolution** - Fixed routing issues and implemented proper layout structure
|
||||
### Recent Updates (March 2026)
|
||||
- ✅ WebSocket real-time trial updates implemented
|
||||
- ✅ Better Auth migration complete (replaced NextAuth.js)
|
||||
- ✅ Docker integration for NAO6 (3 services: nao_driver, ros_bridge, ros_api)
|
||||
- ✅ Conditional branching with wizard choices and convergence
|
||||
- ✅ 14 NAO6 robot actions (speech, movement, gestures, sensors, LEDs, animations)
|
||||
- ✅ Plugin identifier system for clean plugin lookup
|
||||
- ✅ Seed script with branching experiment structure
|
||||
|
||||
### Key Achievements
|
||||
- ✅ Complete backend with 12 tRPC routers
|
||||
- ✅ Professional UI with unified experiences
|
||||
- ✅ Full TypeScript coverage (strict mode)
|
||||
- ✅ Role-based access control (4 roles)
|
||||
- ✅ 31 database tables with relationships
|
||||
- ✅ Experiment designer with 26+ core blocks
|
||||
- ✅ Real-time trial execution wizard interface
|
||||
- ✅ NAO6 robot integration via ROS2 Humble
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ **Implementation Status by Feature**
|
||||
## Architecture
|
||||
|
||||
### **Core Infrastructure** ✅ **Complete**
|
||||
### Three-Layer Architecture
|
||||
|
||||
#### **Plugin Architecture** ✅ **Complete**
|
||||
- **Core Blocks System**: Repository-based architecture with 26 essential blocks
|
||||
- **Robot Plugin Integration**: Unified plugin loading for robot actions
|
||||
- **Repository Management**: Admin tools for plugin repositories and trust levels
|
||||
- **Plugin Store**: Study-scoped plugin installation and configuration
|
||||
- **Block Categories**: Events, wizard actions, control flow, observation blocks
|
||||
- **Type Safety**: Full TypeScript support for all plugin definitions
|
||||
- **Documentation**: Complete guides for core blocks and robot plugins
|
||||
|
||||
|
||||
**Database Schema**
|
||||
- ✅ 31 tables covering all research workflows
|
||||
- ✅ Complete relationships with foreign keys and indexes
|
||||
- ✅ Audit logging and soft deletes implemented
|
||||
- ✅ Performance optimizations with strategic indexing
|
||||
- ✅ JSONB support for flexible metadata storage
|
||||
|
||||
**API Infrastructure**
|
||||
- ✅ 12 tRPC routers providing comprehensive functionality
|
||||
- ✅ Type-safe with Zod validation throughout
|
||||
- ✅ Role-based authorization on all endpoints
|
||||
- ✅ Comprehensive error handling and validation
|
||||
- ✅ Optimistic updates and real-time subscriptions ready
|
||||
|
||||
**Authentication & Authorization**
|
||||
- ✅ NextAuth.js v5 with database sessions
|
||||
- ✅ 4 system roles: Administrator, Researcher, Wizard, Observer
|
||||
- ✅ Role-based middleware protecting all routes
|
||||
- ✅ User profile management with password changes
|
||||
- ✅ Admin dashboard for user and role management
|
||||
|
||||
### **User Interface** ✅ **Complete**
|
||||
|
||||
**Core UI Framework**
|
||||
- ✅ shadcn/ui integration with custom theme
|
||||
- ✅ Responsive design across all screen sizes
|
||||
- ✅ Accessibility compliance (WCAG 2.1 AA)
|
||||
- ✅ Loading states and comprehensive error boundaries
|
||||
- ✅ Form validation with react-hook-form + Zod
|
||||
|
||||
**Major Interface Components**
|
||||
- ✅ Dashboard with role-based navigation
|
||||
- ✅ Authentication pages (signin/signup/profile)
|
||||
- ✅ Study management with team collaboration
|
||||
- ✅ Visual experiment designer with drag-and-drop
|
||||
- ✅ Participant management and consent tracking
|
||||
- ✅ Trial execution and monitoring interfaces
|
||||
- ✅ Data tables with advanced filtering and export
|
||||
|
||||
### **Key Feature Implementations** ✅ **Complete**
|
||||
|
||||
**Visual Experiment Designer**
|
||||
- ✅ Professional drag-and-drop interface
|
||||
- ✅ 4 step types: Wizard Action, Robot Action, Parallel Steps, Conditional Branch
|
||||
- ✅ Real-time saving with conflict resolution
|
||||
- ✅ Parameter configuration framework
|
||||
- ✅ Professional UI with loading states and error handling
|
||||
|
||||
**Unified Editor Experiences**
|
||||
- ✅ Significant reduction in form-related code duplication
|
||||
- ✅ Consistent EntityForm component across all entities
|
||||
- ✅ Standardized validation and error handling
|
||||
- ✅ Context-aware creation for nested workflows
|
||||
- ✅ Progressive workflow guidance with next steps
|
||||
|
||||
**DataTable System**
|
||||
- ✅ Unified DataTable component with enterprise features
|
||||
- ✅ Server-side filtering, sorting, and pagination
|
||||
- ✅ Column visibility controls and export functionality
|
||||
- ✅ Responsive design with proper overflow handling
|
||||
- ✅ Consistent experience across all entity lists
|
||||
|
||||
**Robot Integration Framework**
|
||||
- ✅ Plugin system for extensible robot support
|
||||
- ✅ RESTful API and ROS2 integration via WebSocket
|
||||
- ✅ Type-safe action definitions and parameter schemas
|
||||
- ✅ Connection testing and health monitoring
|
||||
|
||||
---
|
||||
|
||||
## 🎊 **Major Development Achievements**
|
||||
|
||||
### **Code Quality Excellence**
|
||||
- **Type Safety**: Complete TypeScript coverage with strict mode
|
||||
- **Code Reduction**: Significant decrease in form-related duplication
|
||||
- **Performance**: Optimized database queries and client bundles
|
||||
- **Security**: Comprehensive role-based access control
|
||||
- **Testing**: Unit, integration, and E2E testing frameworks ready
|
||||
|
||||
### **User Experience Innovation**
|
||||
- **Consistent Interface**: Unified patterns across all features
|
||||
- **Professional Design**: Enterprise-grade UI components
|
||||
- **Accessibility**: WCAG 2.1 AA compliance throughout
|
||||
- **Responsive**: Mobile-friendly across all screen sizes
|
||||
- **Intuitive Workflows**: Clear progression from study to trial execution
|
||||
|
||||
### **Development Infrastructure**
|
||||
- **Comprehensive Seed Data**: 3 studies, 8 participants, 5 experiments, 7 trials
|
||||
- **Realistic Test Scenarios**: Elementary education, elderly care, navigation trust
|
||||
- **Development Database**: Instant setup with `bun db:seed`
|
||||
- **Documentation**: Complete technical and user documentation
|
||||
|
||||
---
|
||||
|
||||
## ✅ **Trial System Overhaul - COMPLETE**
|
||||
|
||||
### **Visual Design Standardization**
|
||||
- **EntityView Integration**: All trial pages now use unified EntityView patterns
|
||||
- **Consistent Headers**: Standard EntityViewHeader with icons, status badges, and actions
|
||||
- **Sidebar Layout**: Professional EntityViewSidebar with organized information panels
|
||||
- **Breadcrumb Integration**: Proper navigation context throughout trial workflow
|
||||
|
||||
### **Wizard Interface Redesign**
|
||||
- **Panel-Based Architecture**: Adopted PanelsContainer system from experiment designer
|
||||
- **Three-Panel Layout**: Left (controls), Center (execution), Right (monitoring)
|
||||
- **Breadcrumb Navigation**: Proper navigation hierarchy matching platform standards
|
||||
- **Component Reuse**: 90% code sharing with experiment designer patterns
|
||||
- **Real-time Status**: Clean connection indicators without UI flashing
|
||||
- **Resizable Panels**: Drag-to-resize functionality with overflow containment
|
||||
|
||||
### **Component Unification**
|
||||
- **ActionControls**: Updated to match unified component interface patterns
|
||||
- **ParticipantInfo**: Streamlined for sidebar display with essential information
|
||||
- **EventsLogSidebar**: New component for real-time event monitoring
|
||||
- **RobotStatus**: Integrated mock robot simulation for development testing
|
||||
|
||||
### **Technical Improvements**
|
||||
- **WebSocket Stability**: Enhanced connection handling with polling fallback
|
||||
- **Error Management**: Improved development mode error handling without UI flashing
|
||||
- **Type Safety**: Complete TypeScript compatibility across all trial components
|
||||
- **State Management**: Simplified trial state updates and real-time synchronization
|
||||
|
||||
### **Production Capabilities**
|
||||
- **Mock Robot Integration**: Complete simulation for development and testing
|
||||
- **Real-time Execution**: WebSocket-based live updates with automatic fallback
|
||||
- **Data Capture**: Comprehensive event logging and trial progression tracking
|
||||
- **Role-based Access**: Proper wizard, researcher, and observer role enforcement
|
||||
|
||||
---
|
||||
|
||||
## ✅ **Experiment Designer Redesign - COMPLETE**
|
||||
|
||||
### **Development Status**
|
||||
**Priority**: High
|
||||
**Target**: Enhanced visual programming capabilities
|
||||
**Status**: ✅ Complete
|
||||
|
||||
**Completed Enhancements**:
|
||||
- ✅ Enhanced visual programming interface with modern iconography
|
||||
- ✅ Advanced step configuration with parameter editing
|
||||
- ✅ Real-time validation with comprehensive error detection
|
||||
- ✅ Deterministic hashing for reproducibility
|
||||
- ✅ Plugin drift detection and signature tracking
|
||||
- ✅ Modern drag-and-drop interface with @dnd-kit
|
||||
- ✅ Type-safe state management with Zustand
|
||||
- ✅ Export/import functionality with integrity verification
|
||||
|
||||
### **Technical Implementation**
|
||||
```typescript
|
||||
// Completed step configuration interface
|
||||
interface StepConfiguration {
|
||||
type: 'wizard_action' | 'robot_action' | 'parallel' | 'conditional' | 'timer' | 'loop';
|
||||
parameters: StepParameters;
|
||||
validation: ValidationRules;
|
||||
dependencies: StepDependency[];
|
||||
}
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ User Interface Layer │
|
||||
│ ├── Experiment Designer (visual programming) │
|
||||
│ ├── Wizard Interface (trial execution) │
|
||||
│ ├── Observer View (live monitoring) │
|
||||
│ └── Participant View (thesis study) │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ Data Management Layer │
|
||||
│ ├── PostgreSQL + Drizzle ORM │
|
||||
│ ├── tRPC API (12 routers) │
|
||||
│ └── Better Auth (role-based auth) │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ Robot Integration Layer │
|
||||
│ ├── Plugin system (robot-agnostic) │
|
||||
│ ├── ROS2 via rosbridge WebSocket │
|
||||
│ └── Docker deployment (nao_driver, ros_bridge) │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### **Key Fixes Applied**
|
||||
- ✅ **Step Addition Bug**: Fixed JSX structure and type import issues
|
||||
- ✅ **TypeScript Compilation**: All type errors resolved
|
||||
- ✅ **Drag and Drop**: Fully functional with DndContext properly configured
|
||||
- ✅ **State Management**: Zustand store working correctly with all actions
|
||||
- ✅ **UI Layout**: Three-panel layout with Action Library, Step Flow, and Properties
|
||||
### Plugin Identifier System
|
||||
|
||||
```
|
||||
plugins table:
|
||||
- id: UUID (primary key)
|
||||
- identifier: varchar (unique, e.g. "nao6-ros2")
|
||||
- name: varchar (display, e.g. "NAO6 Robot (ROS2)")
|
||||
- robotId: UUID (optional FK to robots)
|
||||
- actionDefinitions: JSONB
|
||||
|
||||
actions table:
|
||||
- type: "plugin.action" (e.g., "nao6-ros2.say_with_emotion")
|
||||
- pluginId: varchar (references plugins.identifier)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 **Sprint Planning & Progress**
|
||||
## Branching Flow
|
||||
|
||||
### **Current Sprint (February 2025)**
|
||||
**Theme**: Production Deployment Preparation
|
||||
Experiment steps support conditional branching with wizard choices:
|
||||
|
||||
**Goals**:
|
||||
1. ✅ Complete experiment designer redesign
|
||||
2. ✅ Fix step addition functionality
|
||||
3. ✅ Resolve TypeScript compilation issues
|
||||
4. ⏳ Final code quality improvements
|
||||
```
|
||||
Step 3 (Comprehension Check)
|
||||
└── wizard_wait_for_response
|
||||
├── Click "Correct" → setLastResponse("Correct") → nextStepId=step4a
|
||||
└── Click "Incorrect" → setLastResponse("Incorrect") → nextStepId=step4b
|
||||
|
||||
**Sprint Metrics**:
|
||||
- **Story Points**: 34 total
|
||||
- **Completed**: 30 points
|
||||
- **In Progress**: 4 points
|
||||
- **Planned**: 0 points
|
||||
Step 4a/4b (Branches)
|
||||
└── conditions.nextStepId: step5.id → convergence point
|
||||
|
||||
### **Development Velocity**
|
||||
- **Sprint 1**: 28 story points completed
|
||||
- **Sprint 2**: 32 story points completed
|
||||
- **Sprint 3**: 34 story points completed
|
||||
- **Sprint 4**: 30 story points completed (current)
|
||||
- **Average**: 31.0 story points per sprint
|
||||
|
||||
### **Quality Metrics**
|
||||
- **Critical Bugs**: Zero (all step addition issues resolved)
|
||||
- **Code Coverage**: High coverage maintained across all components
|
||||
- **Build Time**: Consistently under 3 minutes
|
||||
- **TypeScript Errors**: Zero in production code
|
||||
- **Designer Functionality**: 100% operational
|
||||
Step 5 (Story Continues)
|
||||
└── Linear progression to Step 6
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **Success Criteria Validation**
|
||||
## NAO6 Robot Actions (14 total)
|
||||
|
||||
### **Technical Requirements** ✅ **Met**
|
||||
- ✅ End-to-end type safety throughout platform
|
||||
- ✅ Role-based access control with 4 distinct roles
|
||||
- ✅ Comprehensive API covering all research workflows
|
||||
- ✅ Visual experiment designer with drag-and-drop interface
|
||||
- ✅ Real-time trial execution framework ready
|
||||
- ✅ Scalable architecture built for research teams
|
||||
|
||||
### **User Experience Goals** ✅ **Met**
|
||||
- ✅ Intuitive interface following modern design principles
|
||||
- ✅ Consistent experience across all features
|
||||
- ✅ Responsive design working on all devices
|
||||
- ✅ Accessibility compliance for inclusive research
|
||||
- ✅ Professional appearance suitable for academic use
|
||||
|
||||
### **Research Workflow Support** ✅ **Met**
|
||||
- ✅ Hierarchical study structure (Study → Experiment → Trial → Step → Action)
|
||||
- ✅ Multi-role collaboration with proper permissions
|
||||
- ✅ Comprehensive data capture for all trial activities
|
||||
- ✅ Flexible robot integration supporting multiple platforms
|
||||
- ✅ Data analysis and export capabilities
|
||||
| Category | Actions |
|
||||
|----------|---------|
|
||||
| Speech | say, say_with_emotion, wave_goodbye |
|
||||
| Movement | walk, turn, move_to_posture |
|
||||
| Gestures | play_animation, gesture |
|
||||
| Sensors | get_sensors, bumper_state, touch_state |
|
||||
| LEDs | set_eye_leds, set_breathing_lights |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **Production Readiness**
|
||||
## Tech Stack
|
||||
|
||||
### **Deployment Checklist** ✅ **Complete**
|
||||
- ✅ Environment variables configured for Vercel
|
||||
- ✅ Database migrations ready for production
|
||||
- ✅ Security headers and CSRF protection configured
|
||||
- ✅ Error tracking and performance monitoring setup
|
||||
- ✅ Build process optimized for Edge Runtime
|
||||
- ✅ Static assets and CDN configuration ready
|
||||
|
||||
### **Performance Validation** ✅ **Passed**
|
||||
- ✅ Page load time < 2 seconds (Currently optimal)
|
||||
- ✅ API response time < 200ms (Currently optimal)
|
||||
- ✅ Database query time < 50ms (Currently optimal)
|
||||
- ✅ Build completes in < 3 minutes (Currently optimal)
|
||||
- ✅ Zero TypeScript compilation errors
|
||||
- ✅ All ESLint rules passing
|
||||
|
||||
### **Security Validation** ✅ **Verified**
|
||||
- ✅ Role-based access control at all levels
|
||||
- ✅ Input validation and sanitization comprehensive
|
||||
- ✅ SQL injection protection via Drizzle ORM
|
||||
- ✅ XSS prevention with proper content handling
|
||||
- ✅ Secure session management with NextAuth.js
|
||||
- ✅ Audit logging for all sensitive operations
|
||||
| Component | Technology | Version |
|
||||
|-----------|------------|---------|
|
||||
| Framework | Next.js | 15-16.x |
|
||||
| Language | TypeScript | 5.x (strict) |
|
||||
| Database | PostgreSQL | 14+ |
|
||||
| ORM | Drizzle | latest |
|
||||
| Auth | NextAuth.js | v5 |
|
||||
| API | tRPC | latest |
|
||||
| UI | Tailwind + shadcn/ui | latest |
|
||||
| Real-time | WebSocket | with polling fallback |
|
||||
| Robot | ROS2 Humble | via rosbridge |
|
||||
| Package Manager | Bun | latest |
|
||||
|
||||
---
|
||||
|
||||
## 📈 **Platform Capabilities**
|
||||
## Development Status
|
||||
|
||||
### **Research Workflow Support**
|
||||
- **Study Management**: Complete lifecycle from creation to analysis
|
||||
- **Team Collaboration**: Multi-user support with role-based permissions
|
||||
- **Experiment Design**: Visual programming interface for protocol creation
|
||||
- **Trial Execution**: Panel-based wizard interface matching experiment designer architecture
|
||||
- **Real-time Updates**: WebSocket integration with intelligent polling fallback
|
||||
- **Data Capture**: Synchronized multi-modal data streams with comprehensive event logging
|
||||
- **Robot Integration**: Plugin-based support for multiple platforms
|
||||
### Completed Features
|
||||
| Feature | Status | Notes |
|
||||
|---------|--------|-------|
|
||||
| Database Schema | ✅ | 31 tables |
|
||||
| Authentication | ✅ | 4 roles |
|
||||
| Experiment Designer | ✅ | 26+ blocks |
|
||||
| Wizard Interface | ✅ | 3-panel design |
|
||||
| Real-time Updates | ✅ | WebSocket |
|
||||
| Plugin System | ✅ | Robot-agnostic |
|
||||
| NAO6 Integration | ✅ | Docker deployment |
|
||||
| Conditional Branching | ✅ | Wizard choices |
|
||||
| Mock Robot | ✅ | Development mode |
|
||||
|
||||
### **Technical Capabilities**
|
||||
- **Scalability**: Architecture supporting large research institutions
|
||||
- **Performance**: Optimized for concurrent multi-user environments
|
||||
- **Security**: Research-grade data protection and access control
|
||||
- **Flexibility**: Customizable workflows for diverse methodologies
|
||||
- **Integration**: Robot platform agnostic with plugin architecture
|
||||
- **Compliance**: Research ethics and data protection compliance
|
||||
### Known Issues
|
||||
| Issue | Status | Notes |
|
||||
|-------|--------|-------|
|
||||
| robots.executeSystemAction | Known error | Fallback works |
|
||||
|
||||
---
|
||||
|
||||
## 🔮 **Roadmap & Future Work**
|
||||
## SSH Deployment Commands
|
||||
|
||||
### **Immediate Priorities** (Next 30 days)
|
||||
- **Wizard Interface Development** - Complete rebuild of trial execution interface
|
||||
- **Robot Control Implementation** - NAO6 integration with WebSocket communication
|
||||
- **Trial Execution Engine** - Step-by-step protocol execution with real-time data capture
|
||||
- **User Experience Testing** - Validate study-scoped workflows with target users
|
||||
```bash
|
||||
# Local development
|
||||
bun dev
|
||||
|
||||
### **Short-term Goals** (Next 60 days)
|
||||
- **IRB Application Preparation** - Complete documentation and study protocols
|
||||
- **Reference Experiment Implementation** - Well-documented HRI experiment for comparison study
|
||||
- **Training Materials Development** - Comprehensive materials for both HRIStudio and Choregraphe
|
||||
- **Platform Validation** - Extensive testing and reliability verification
|
||||
# Database
|
||||
bun db:push # Push schema changes
|
||||
bun db:seed # Seed with test data
|
||||
bun run docker:up # Start PostgreSQL
|
||||
|
||||
### **Long-term Vision** (Next 90+ days)
|
||||
- **User Study Execution** - Comparative study with 10-12 non-engineering participants
|
||||
- **Thesis Research Completion** - Data analysis and academic paper preparation
|
||||
- **Platform Refinement** - Post-study improvements based on real user feedback
|
||||
- **Community Release** - Open source release for broader HRI research community
|
||||
# Quality
|
||||
bun typecheck # TypeScript validation
|
||||
bun lint # ESLint
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎊 **Project Success Declaration**
|
||||
## Thesis Timeline
|
||||
|
||||
**HRIStudio is officially ready for production deployment.**
|
||||
Current phase: **March 2026** - Implementation complete, preparing user study
|
||||
|
||||
### **Completion Summary**
|
||||
The platform successfully provides researchers with a comprehensive, professional, and scientifically rigorous environment for conducting Wizard of Oz studies in Human-Robot Interaction research. All major development goals have been achieved, including the complete modernization of the experiment designer with advanced visual programming capabilities and the successful consolidation of routes into a logical study-scoped architecture. Quality standards have been exceeded, and the system is prepared for thesis research and eventual community use.
|
||||
|
||||
### **Key Success Metrics**
|
||||
- **Development Velocity**: Consistently meeting sprint goals with 30+ story points
|
||||
- **Code Quality**: Zero production TypeScript errors, fully functional designer
|
||||
- **Architecture Quality**: Clean study-scoped hierarchy with eliminated code duplication
|
||||
- **User Experience**: Intuitive navigation flow from studies to entity management
|
||||
- **Route Health**: All routes functional with proper error handling and helpful redirects
|
||||
- **User Experience**: Professional, accessible, consistent interface with modern UX
|
||||
- **Performance**: All benchmarks exceeded, sub-100ms hash computation
|
||||
- **Security**: Comprehensive protection and compliance
|
||||
- **Documentation**: Complete technical and user guides
|
||||
- **Designer Functionality**: 100% operational with step addition working perfectly
|
||||
|
||||
### **Ready For**
|
||||
- ✅ Immediate Vercel deployment
|
||||
- ✅ Research team onboarding
|
||||
- ✅ Academic pilot studies
|
||||
- ✅ Full production research use
|
||||
- ✅ Institutional deployment
|
||||
|
||||
**The development team has successfully delivered a world-class platform that will advance Human-Robot Interaction research by providing standardized, reproducible, and efficient tools for conducting high-quality scientific studies.**
|
||||
| Phase | Status | Date |
|
||||
|-------|--------|------|
|
||||
| Proposal | ✅ | Sept 2025 |
|
||||
| IRB Application | ✅ | Dec 2025 |
|
||||
| Implementation | ✅ | Feb 2026 |
|
||||
| User Study | 🔄 In Progress | Mar-Apr 2026 |
|
||||
| Defense | Scheduled | April 2026 |
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **Development Notes**
|
||||
## Next Steps
|
||||
|
||||
### **Technical Debt Status**
|
||||
- **High Priority**: None identified
|
||||
- **Medium Priority**: Minor database query optimizations possible
|
||||
- **Low Priority**: Some older components could benefit from modern React patterns
|
||||
|
||||
### **Development Restrictions**
|
||||
Following Vercel Edge Runtime compatibility:
|
||||
- ❌ No development servers during implementation sessions
|
||||
- ❌ No Drizzle Studio during development work
|
||||
- ✅ Use `bun db:push` for schema changes
|
||||
- ✅ Use `bun typecheck` for validation
|
||||
- ✅ Use `bun build` for production testing
|
||||
|
||||
### **Quality Gates**
|
||||
- ✅ All TypeScript compilation errors resolved
|
||||
- ✅ All ESLint rules passing with autofix enabled
|
||||
- ✅ All Prettier formatting applied consistently
|
||||
- ✅ No security vulnerabilities detected
|
||||
- ✅ Performance benchmarks met
|
||||
- ✅ Accessibility standards validated
|
||||
1. Complete user study (10-12 participants)
|
||||
2. Data analysis and thesis writing
|
||||
3. Final defense April 2026
|
||||
4. Open source release
|
||||
|
||||
---
|
||||
|
||||
*This document consolidates all project status, progress tracking, and achievement documentation. It serves as the single source of truth for HRIStudio's development state and production readiness.*
|
||||
*Last Updated: March 22, 2026*
|
||||
@@ -107,7 +107,7 @@ This work addresses a significant bottleneck in HRI research. By creating HRIStu
|
||||
\hline
|
||||
September & Finalize and submit this proposal (Due: Sept. 20).
|
||||
|
||||
Submit IRB application for the user study. \\
|
||||
Submit IRB application for the study. \\
|
||||
\hline
|
||||
Oct -- Nov & Complete final implementation of core HRIStudio features.
|
||||
|
||||
@@ -119,13 +119,15 @@ Begin recruiting participants. \\
|
||||
\hline
|
||||
\multicolumn{2}{|l|}{\textbf{Spring 2026: Execution, Analysis, and Writing}} \\
|
||||
\hline
|
||||
Jan -- Feb & Upon receiving IRB approval, conduct all user study sessions. \\
|
||||
Jan -- Feb & Run pilot tests with platform.
|
||||
|
||||
Refine based on testing feedback. \\
|
||||
\hline
|
||||
March & Analyze all data from the user study.
|
||||
March & Execute user study sessions (10-12 participants).
|
||||
|
||||
Draft Results and Discussion sections.
|
||||
Analyze data from the user study.
|
||||
|
||||
Submit ``Intent to Defend'' form (Due: March 1). \\
|
||||
Draft Results and Discussion sections. \\
|
||||
\hline
|
||||
April & Submit completed thesis draft to the defense committee (Due: April 1).
|
||||
|
||||
|
||||
@@ -1,67 +1,30 @@
|
||||
# HRIStudio Quick Reference Guide
|
||||
|
||||
## 🚀 **Getting Started (5 Minutes)**
|
||||
## Quick Setup
|
||||
|
||||
### Prerequisites
|
||||
- [Bun](https://bun.sh) (package manager)
|
||||
- [PostgreSQL](https://postgresql.org) 14+
|
||||
- [Docker](https://docker.com) (optional)
|
||||
|
||||
### Quick Setup
|
||||
```bash
|
||||
# Clone and install
|
||||
git clone <repo-url> hristudio
|
||||
# Clone with submodules
|
||||
git clone https://github.com/soconnor0919/hristudio.git
|
||||
cd hristudio
|
||||
git submodule update --init --recursive
|
||||
|
||||
# Install and setup
|
||||
bun install
|
||||
|
||||
# Start database
|
||||
bun run docker:up
|
||||
|
||||
# Setup database
|
||||
bun db:push
|
||||
bun db:seed
|
||||
|
||||
# Single command now syncs all repositories:
|
||||
# - Core blocks from localhost:3000/hristudio-core
|
||||
# - Robot plugins from https://repo.hristudio.com
|
||||
|
||||
# Start development
|
||||
# Start
|
||||
bun dev
|
||||
```
|
||||
|
||||
### Default Login
|
||||
- **Admin**: `sean@soconnor.dev` / `password123`
|
||||
- **Researcher**: `alice.rodriguez@university.edu` / `password123`
|
||||
- **Wizard**: `emily.watson@lab.edu` / `password123`
|
||||
**Login**: `sean@soconnor.dev` / `password123`
|
||||
|
||||
---
|
||||
|
||||
## 📁 **Project Structure**
|
||||
## Key Concepts
|
||||
|
||||
```
|
||||
src/
|
||||
├── app/ # Next.js App Router pages
|
||||
│ ├── (auth)/ # Authentication pages
|
||||
│ ├── (dashboard)/ # Main application
|
||||
│ └── api/ # API routes
|
||||
├── components/ # UI components
|
||||
│ ├── ui/ # shadcn/ui components
|
||||
│ ├── experiments/ # Feature components
|
||||
│ ├── studies/
|
||||
│ ├── participants/
|
||||
│ └── trials/
|
||||
├── server/ # Backend code
|
||||
│ ├── api/routers/ # tRPC routers
|
||||
│ ├── auth/ # NextAuth config
|
||||
│ └── db/ # Database schema
|
||||
└── lib/ # Utilities
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **Key Concepts**
|
||||
|
||||
### Hierarchical Structure
|
||||
### Hierarchy
|
||||
```
|
||||
Study → Experiment → Trial → Step → Action
|
||||
```
|
||||
@@ -70,530 +33,117 @@ Study → Experiment → Trial → Step → Action
|
||||
- **Administrator**: Full system access
|
||||
- **Researcher**: Create studies, design experiments
|
||||
- **Wizard**: Execute trials, control robots
|
||||
- **Observer**: Read-only access
|
||||
- **Observer**: Read-only monitoring
|
||||
|
||||
### Core Workflows
|
||||
1. **Study Creation** → Team setup → Participant recruitment
|
||||
2. **Experiment Design** → Visual designer → Protocol validation
|
||||
3. **Trial Execution** → Wizard interface → Data capture
|
||||
4. **Data Analysis** → Export → Insights
|
||||
### Plugin Identifier System
|
||||
- `identifier`: Machine-readable key (e.g., `nao6-ros2`)
|
||||
- `name`: Display name (e.g., `NAO6 Robot (ROS2 Integration)`)
|
||||
- Lookup order: identifier → name → fallback
|
||||
|
||||
---
|
||||
|
||||
## 🛠 **Development Commands**
|
||||
## Development Commands
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `bun dev` | Start development server |
|
||||
| `bun build` | Build for production |
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `bun dev` | Start dev server |
|
||||
| `bun build` | Production build |
|
||||
| `bun typecheck` | TypeScript validation |
|
||||
| `bun lint` | Code quality checks |
|
||||
| `bun db:push` | Push schema changes |
|
||||
| `bun db:seed` | Seed data & sync repositories |
|
||||
| `bun db:studio` | Open database GUI |
|
||||
| `bun db:seed` | Seed data + sync plugins |
|
||||
| `bun run docker:up` | Start PostgreSQL |
|
||||
|
||||
---
|
||||
|
||||
## 🌐 **API Reference**
|
||||
## NAO6 Robot Docker
|
||||
|
||||
### Base URL
|
||||
```
|
||||
http://localhost:3000/api/trpc/
|
||||
```
|
||||
|
||||
### Key Routers
|
||||
- **`auth`**: Login, logout, registration
|
||||
- **`studies`**: CRUD operations, team management
|
||||
- **`experiments`**: Design, configuration, validation
|
||||
- **`participants`**: Registration, consent, demographics
|
||||
- **`trials`**: Execution, monitoring, data capture, real-time control
|
||||
- **`robots`**: Integration, communication, actions, plugins
|
||||
- **`dashboard`**: Overview stats, recent activity, study progress
|
||||
- **`admin`**: Repository management, system settings
|
||||
|
||||
---
|
||||
|
||||
## 🤖 NAO6 Docker Integration
|
||||
|
||||
### Quick Start
|
||||
```bash
|
||||
cd ~/Documents/Projects/nao6-hristudio-integration
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Robot automatically wakes up and disables autonomous life on startup.
|
||||
**Services**: nao_driver, ros_bridge (:9090), ros_api
|
||||
|
||||
**Topics**:
|
||||
- `/speech` - TTS
|
||||
- `/cmd_vel` - Movement
|
||||
- `/leds/eyes` - LEDs
|
||||
|
||||
---
|
||||
|
||||
## Architecture Layers
|
||||
|
||||
### ROS Topics
|
||||
```
|
||||
/speech - Text-to-speech
|
||||
/cmd_vel - Movement commands
|
||||
/joint_angles - Joint position control
|
||||
/camera/front/image_raw
|
||||
/camera/bottom/image_raw
|
||||
/imu/torso
|
||||
/bumper
|
||||
/{hand,head}_touch
|
||||
/sonar/{left,right}
|
||||
/info
|
||||
```
|
||||
|
||||
### Plugin System
|
||||
- Plugin identifier: `nao6-ros2`
|
||||
- Plugin name: `NAO6 Robot (ROS2 Integration)`
|
||||
- Action types: `nao6-ros2.say_with_emotion`, `nao6-ros2.move_arm`, etc.
|
||||
|
||||
See [nao6-quick-reference.md](./nao6-quick-reference.md) for full details.
|
||||
|
||||
### Example Usage
|
||||
```typescript
|
||||
// Get user's studies
|
||||
const studies = api.studies.getUserStudies.useQuery();
|
||||
|
||||
// Create new experiment
|
||||
const createExperiment = api.experiments.create.useMutation();
|
||||
┌─────────────────────────────────────┐
|
||||
│ UI: Design / Execute / Playback │
|
||||
├─────────────────────────────────────┤
|
||||
│ Server: tRPC, Auth, Trial Logic │
|
||||
├─────────────────────────────────────┤
|
||||
│ Data: PostgreSQL, File Storage │
|
||||
│ Robot: ROS2 via WebSocket │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ **Database Quick Reference**
|
||||
## WebSocket Architecture
|
||||
|
||||
- **Trial Updates**: `ws://localhost:3001/api/websocket`
|
||||
- **ROS Bridge**: `ws://localhost:9090` (rosbridge)
|
||||
- **Real-time**: Auto-reconnect with exponential backoff
|
||||
- **Message Types**: trial_event, trial_status, connection_established
|
||||
|
||||
---
|
||||
|
||||
## Database Schema
|
||||
|
||||
### Core Tables
|
||||
```sql
|
||||
users -- Authentication & profiles
|
||||
studies -- Research projects
|
||||
experiments -- Protocol templates
|
||||
participants -- Study participants
|
||||
trials -- Experiment instances
|
||||
steps -- Experiment phases
|
||||
trial_events -- Execution logs
|
||||
robots -- Available platforms
|
||||
```
|
||||
- `users` - Authentication
|
||||
- `studies` - Research projects
|
||||
- `experiments` - Protocol templates
|
||||
- `trials` - Execution instances
|
||||
- `steps` - Experiment phases
|
||||
- `actions` - Atomic tasks
|
||||
- `plugins` - Robot integrations (identifier column)
|
||||
- `trial_events` - Execution logs
|
||||
|
||||
---
|
||||
|
||||
## Route Structure
|
||||
|
||||
### Key Relationships
|
||||
```
|
||||
studies → experiments → trials
|
||||
studies → participants
|
||||
trials → trial_events
|
||||
experiments → steps
|
||||
/dashboard - Global overview
|
||||
/studies - Study list
|
||||
/studies/[id] - Study details
|
||||
/studies/[id]/experiments
|
||||
/studies/[id]/trials
|
||||
/studies/[id]/participants
|
||||
/trials/[id]/wizard - Trial execution
|
||||
/experiments/[id]/designer - Visual editor
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 **UI Components**
|
||||
## Troubleshooting
|
||||
|
||||
**Build errors**: `rm -rf .next && bun build`
|
||||
|
||||
**Database reset**: `bun db:push --force && bun db:seed`
|
||||
|
||||
**Check types**: `bun typecheck`
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **Trial System Quick Reference**
|
||||
## Plugin System
|
||||
|
||||
### Trial Workflow
|
||||
```
|
||||
1. Create Study → 2. Design Experiment → 3. Add Participants → 4. Schedule Trial → 5. Execute with Wizard Interface → 6. Analyze Results
|
||||
```
|
||||
|
||||
### Key Trial Pages
|
||||
- **`/studies/[id]/trials`**: List trials for specific study
|
||||
- **`/trials/[id]`**: Individual trial details and management
|
||||
- **`/trials/[id]/wizard`**: Panel-based real-time execution interface
|
||||
- **`/trials/[id]/analysis`**: Post-trial data analysis
|
||||
|
||||
### Trial Status Flow
|
||||
```
|
||||
scheduled → in_progress → completed
|
||||
↘ aborted
|
||||
↘ failed
|
||||
```
|
||||
|
||||
### Wizard Interface Architecture (Panel-Based)
|
||||
The wizard interface uses the same proven panel system as the experiment designer:
|
||||
|
||||
#### **Layout Components**
|
||||
- **PageHeader**: Consistent navigation with breadcrumbs
|
||||
- **PanelsContainer**: Three-panel resizable layout
|
||||
- **Proper Navigation**: Dashboard → Studies → [Study] → Trials → [Trial] → Wizard Control
|
||||
|
||||
#### **Panel Organization**
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ PageHeader: Wizard Control │
|
||||
├──────────┬─────────────────────────┬────────────────────┤
|
||||
│ Left │ Center │ Right │
|
||||
│ Panel │ Panel │ Panel │
|
||||
│ │ │ │
|
||||
│ Trial │ Current Step │ Robot Status │
|
||||
│ Controls │ & Wizard Actions │ Participant Info │
|
||||
│ Step │ │ Live Events │
|
||||
│ List │ │ Connection Status │
|
||||
└──────────┴─────────────────────────┴────────────────────┘
|
||||
```
|
||||
|
||||
#### **Panel Features**
|
||||
- **Left Panel**: Trial controls, status, step navigation
|
||||
- **Center Panel**: Main execution area with current step and wizard actions
|
||||
- **Right Panel**: Real-time monitoring and context information
|
||||
- **Resizable**: Drag separators to adjust panel sizes
|
||||
- **Overflow Contained**: No page-level scrolling, internal panel scrolling
|
||||
|
||||
### Technical Features
|
||||
- **Real-time Control**: Step-by-step protocol execution
|
||||
- **WebSocket Integration**: Live updates with polling fallback
|
||||
- **Component Reuse**: 90% code sharing with experiment designer
|
||||
- **Type Safety**: Complete TypeScript compatibility
|
||||
- **Mock Robot System**: TurtleBot3 simulation ready for development
|
||||
|
||||
---
|
||||
|
||||
### Layout Components
|
||||
```typescript
|
||||
// Page wrapper with navigation
|
||||
<PageLayout title="Studies" description="Manage research studies">
|
||||
<StudiesTable />
|
||||
</PageLayout>
|
||||
// Loading a plugin by identifier
|
||||
const plugin = await trialExecution.loadPlugin("nao6-ros2");
|
||||
|
||||
// Entity forms (unified pattern)
|
||||
<EntityForm
|
||||
mode="create"
|
||||
entityName="Study"
|
||||
form={form}
|
||||
onSubmit={handleSubmit}
|
||||
/>
|
||||
|
||||
// Data tables (consistent across entities)
|
||||
<DataTable
|
||||
columns={studiesColumns}
|
||||
data={studies}
|
||||
searchKey="name"
|
||||
/>
|
||||
```
|
||||
|
||||
### Form Patterns
|
||||
```typescript
|
||||
// Standard form setup
|
||||
const form = useForm<StudyFormData>({
|
||||
resolver: zodResolver(studySchema),
|
||||
defaultValues: { /* ... */ }
|
||||
});
|
||||
|
||||
// Unified submission
|
||||
const onSubmit = async (data: StudyFormData) => {
|
||||
await createStudy.mutateAsync(data);
|
||||
router.push(`/studies/${result.id}`);
|
||||
};
|
||||
// Action execution
|
||||
await robot.execute("nao6-ros2.say_with_emotion", { text: "Hello" });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **Route Structure**
|
||||
|
||||
### Study-Scoped Architecture
|
||||
All study-dependent functionality flows through studies for complete organizational consistency:
|
||||
|
||||
```
|
||||
Platform Routes (Global):
|
||||
/dashboard # Global overview with study filtering
|
||||
/studies # Study management hub
|
||||
/profile # User account management
|
||||
/admin # System administration
|
||||
|
||||
Study-Scoped Routes (All Study-Dependent):
|
||||
/studies/[id] # Study details and overview
|
||||
/studies/[id]/participants # Study participants
|
||||
/studies/[id]/trials # Study trials
|
||||
/studies/[id]/experiments # Study experiment protocols
|
||||
/studies/[id]/plugins # Study robot plugins
|
||||
/studies/[id]/analytics # Study analytics
|
||||
|
||||
Individual Entity Routes (Cross-Study):
|
||||
/trials/[id] # Individual trial details
|
||||
/trials/[id]/wizard # Trial execution interface (TO BE BUILT)
|
||||
/experiments/[id] # Individual experiment details
|
||||
/experiments/[id]/designer # Visual experiment designer
|
||||
|
||||
Helpful Redirects (User Guidance):
|
||||
/participants # → Study selection guidance
|
||||
/trials # → Study selection guidance
|
||||
/experiments # → Study selection guidance
|
||||
/plugins # → Study selection guidance
|
||||
/analytics # → Study selection guidance
|
||||
```
|
||||
|
||||
### Architecture Benefits
|
||||
- **Complete Consistency**: All study-dependent functionality properly scoped
|
||||
- **Clear Mental Model**: Platform-level vs study-level separation
|
||||
- **No Duplication**: Single source of truth for each functionality
|
||||
- **User-Friendly**: Helpful guidance for moved functionality
|
||||
|
||||
## 🔐 **Authentication**
|
||||
|
||||
### Protecting Routes
|
||||
```typescript
|
||||
// Middleware protection
|
||||
export default withAuth(
|
||||
function middleware(request) {
|
||||
// Route logic
|
||||
},
|
||||
{
|
||||
callbacks: {
|
||||
authorized: ({ token }) => !!token,
|
||||
},
|
||||
}
|
||||
);
|
||||
|
||||
// Component protection
|
||||
const { data: session, status } = useSession();
|
||||
if (status === "loading") return <Loading />;
|
||||
if (!session) return <SignIn />;
|
||||
```
|
||||
|
||||
### Role Checking
|
||||
```typescript
|
||||
// Server-side
|
||||
ctx.session.user.role === "administrator"
|
||||
|
||||
// Client-side
|
||||
import { useSession } from "next-auth/react";
|
||||
const hasRole = (role: string) => session?.user.role === role;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤖 **Robot Integration**
|
||||
|
||||
### Core Block System
|
||||
```typescript
|
||||
// Core blocks loaded from local repository during development
|
||||
// Repository sync: localhost:3000/hristudio-core → database
|
||||
|
||||
// Block categories (27 total blocks in 4 groups):
|
||||
// - Events (4): when_trial_starts, when_participant_speaks, etc.
|
||||
// - Wizard Actions (6): wizard_say, wizard_gesture, etc.
|
||||
// - Control Flow (8): wait, repeat, if_condition, etc.
|
||||
// - Observation (9): observe_behavior, record_audio, etc.
|
||||
```
|
||||
|
||||
### Plugin Repository System
|
||||
```typescript
|
||||
// Repository sync (admin only)
|
||||
await api.admin.repositories.sync.mutate({ id: repoId });
|
||||
|
||||
// Plugin installation
|
||||
await api.robots.plugins.install.mutate({
|
||||
studyId: 'study-id',
|
||||
pluginId: 'plugin-id'
|
||||
});
|
||||
|
||||
// Get study plugins
|
||||
const plugins = api.robots.plugins.getStudyPlugins.useQuery({
|
||||
studyId: selectedStudyId
|
||||
});
|
||||
```
|
||||
|
||||
### Plugin Structure
|
||||
```typescript
|
||||
interface Plugin {
|
||||
id: string;
|
||||
name: string;
|
||||
version: string;
|
||||
trustLevel: 'official' | 'verified' | 'community';
|
||||
actionDefinitions: RobotAction[];
|
||||
metadata: {
|
||||
platform: string;
|
||||
category: string;
|
||||
repositoryId: string;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Repository Integration
|
||||
- **Robot Plugins**: `https://repo.hristudio.com` (live)
|
||||
- **Core Blocks**: `localhost:3000/hristudio-core` (development)
|
||||
- **Auto-sync**: Integrated into `bun db:seed` command
|
||||
- **Plugin Store**: Browse → Install → Use in experiments
|
||||
|
||||
---
|
||||
|
||||
## 📊 **Common Patterns**
|
||||
|
||||
### Error Handling
|
||||
```typescript
|
||||
try {
|
||||
await mutation.mutateAsync(data);
|
||||
toast.success("Success!");
|
||||
router.push("/success-page");
|
||||
} catch (error) {
|
||||
setError(error.message);
|
||||
toast.error("Failed to save");
|
||||
}
|
||||
```
|
||||
|
||||
### Loading States
|
||||
```typescript
|
||||
const { data, isLoading, error } = api.studies.getAll.useQuery();
|
||||
|
||||
if (isLoading) return <Skeleton />;
|
||||
if (error) return <ErrorMessage error={error} />;
|
||||
return <DataTable data={data} />;
|
||||
```
|
||||
|
||||
### Form Validation
|
||||
```typescript
|
||||
const schema = z.object({
|
||||
name: z.string().min(1, "Name required"),
|
||||
description: z.string().min(10, "Description too short"),
|
||||
duration: z.number().min(5, "Minimum 5 minutes")
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **Deployment**
|
||||
|
||||
### Vercel Deployment
|
||||
```bash
|
||||
# Install Vercel CLI
|
||||
bun add -g vercel
|
||||
|
||||
# Deploy
|
||||
vercel --prod
|
||||
|
||||
# Environment variables
|
||||
vercel env add DATABASE_URL
|
||||
vercel env add NEXTAUTH_SECRET
|
||||
vercel env add CLOUDFLARE_R2_*
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
# Required
|
||||
DATABASE_URL=postgresql://...
|
||||
NEXTAUTH_URL=https://your-domain.com
|
||||
NEXTAUTH_SECRET=your-secret
|
||||
|
||||
# Storage
|
||||
CLOUDFLARE_R2_ACCOUNT_ID=...
|
||||
CLOUDFLARE_R2_ACCESS_KEY_ID=...
|
||||
CLOUDFLARE_R2_SECRET_ACCESS_KEY=...
|
||||
CLOUDFLARE_R2_BUCKET_NAME=hristudio-files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Experiment Designer — Quick Tips
|
||||
|
||||
- Panels layout
|
||||
- Uses Tailwind-first grid via `PanelsContainer` with fraction-based columns (no hardcoded px).
|
||||
- Left/Center/Right panels are minmax(0, …) columns to prevent horizontal overflow.
|
||||
- Status bar lives inside the bordered container; no gap below the panels.
|
||||
|
||||
- Resizing (no persistence)
|
||||
- Drag separators between Left↔Center and Center↔Right to resize panels.
|
||||
- Fractions are clamped (min/max) to keep panels usable and avoid page overflow.
|
||||
- Keyboard on handles: Arrow keys to resize; Shift+Arrow for larger steps.
|
||||
|
||||
- Overflow rules (no page-level X scroll)
|
||||
- Root containers: `overflow-hidden`, `min-h-0`.
|
||||
- Each panel wrapper: `min-w-0 overflow-hidden`.
|
||||
- Each panel content: `overflow-y-auto overflow-x-hidden` (scroll inside the panel).
|
||||
- If X scroll appears, clamp the offending child (truncate, `break-words`, `overflow-x-hidden`).
|
||||
|
||||
- Action Library scroll
|
||||
- Search/categories header and footer are fixed; the list uses internal scroll (`ScrollArea` with `flex-1`).
|
||||
- Long lists never scroll the page — only the panel.
|
||||
|
||||
- Inspector tabs (shadcn/ui)
|
||||
- Single Tabs root controls both header and content.
|
||||
- TabsList uses simple grid or inline-flex; triggers are plain `TabsTrigger`.
|
||||
- Active state is styled globally (via `globals.css`) using Radix `data-state="active"`.
|
||||
|
||||
## 🔧 **Troubleshooting**
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Build Errors**
|
||||
```bash
|
||||
# Clear cache and rebuild
|
||||
rm -rf .next
|
||||
bun run build
|
||||
```
|
||||
|
||||
**Database Issues**
|
||||
```bash
|
||||
# Reset database
|
||||
bun db:push --force
|
||||
bun db:seed
|
||||
```
|
||||
|
||||
**TypeScript Errors**
|
||||
```bash
|
||||
# Check types
|
||||
bun typecheck
|
||||
|
||||
# Common fixes
|
||||
# - Check imports
|
||||
# - Verify API return types
|
||||
# - Update schema types
|
||||
```
|
||||
|
||||
### Performance Tips
|
||||
- Use React Server Components where possible
|
||||
- Implement proper pagination for large datasets
|
||||
- Add database indexes for frequently queried fields
|
||||
- Use optimistic updates for better UX
|
||||
|
||||
---
|
||||
|
||||
## 📚 **Further Reading**
|
||||
|
||||
### Documentation Files
|
||||
- **[Project Overview](./project-overview.md)**: Complete feature overview
|
||||
- **[Implementation Details](./implementation-details.md)**: Architecture decisions and patterns
|
||||
- **[Database Schema](./database-schema.md)**: Complete database documentation
|
||||
- **[API Routes](./api-routes.md)**: Comprehensive API reference
|
||||
- **[Core Blocks System](./core-blocks-system.md)**: Repository-based block architecture
|
||||
- **[Plugin System Guide](./plugin-system-implementation-guide.md)**: Robot integration guide
|
||||
- **[Project Status](./project-status.md)**: Current development status
|
||||
- **[Work in Progress](./work_in_progress.md)**: Recent changes and active development
|
||||
|
||||
### External Resources
|
||||
- [Next.js Documentation](https://nextjs.org/docs)
|
||||
- [tRPC Documentation](https://trpc.io/docs)
|
||||
- [Drizzle ORM Guide](https://orm.drizzle.team/docs)
|
||||
- [shadcn/ui Components](https://ui.shadcn.com)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **Quick Tips**
|
||||
### Quick Tips
|
||||
|
||||
### Development Workflow
|
||||
1. Always run `bun typecheck` before commits
|
||||
2. Use the unified `EntityForm` for all CRUD operations
|
||||
3. Follow the established component patterns
|
||||
4. Add proper error boundaries for new features
|
||||
5. Test with multiple user roles
|
||||
6. Use single `bun db:seed` for complete setup
|
||||
|
||||
### Code Standards
|
||||
- Use TypeScript strict mode
|
||||
- Prefer Server Components over Client Components
|
||||
- Implement proper error handling
|
||||
- Add loading states for all async operations
|
||||
- Use Zod for input validation
|
||||
|
||||
### Best Practices
|
||||
- Keep components focused and composable
|
||||
- Use the established file naming conventions
|
||||
- Implement proper RBAC for new features
|
||||
- Add comprehensive logging for debugging
|
||||
- Follow accessibility guidelines (WCAG 2.1 AA)
|
||||
- Use repository-based plugins instead of hardcoded robot actions
|
||||
- Test plugin installation/uninstallation in different studies
|
||||
|
||||
### Route Architecture
|
||||
- **Study-Scoped**: All entity management flows through studies
|
||||
- **Individual Entities**: Trial/experiment details maintain separate routes
|
||||
- **Helpful Redirects**: Old routes guide users to new locations
|
||||
- **Consistent Navigation**: Breadcrumbs reflect the study → entity hierarchy
|
||||
|
||||
---
|
||||
|
||||
*This quick reference covers the most commonly needed information for HRIStudio development. For detailed implementation guidance, refer to the comprehensive documentation files.*
|
||||
Last updated: March 2026
|
||||
Reference in New Issue
Block a user