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:
48
README.md
48
README.md
@@ -64,16 +64,15 @@ bun dev
|
|||||||
|
|
||||||
## Technology Stack
|
## Technology Stack
|
||||||
|
|
||||||
- **Framework**: Next.js 15 with App Router and React 19 RC
|
- **Framework**: Next.js 15 (16.x compatible) with App Router and React 19
|
||||||
- **Language**: TypeScript (strict mode) - 100% type safety throughout
|
- **Language**: TypeScript (strict mode) - 100% type safety throughout
|
||||||
- **Database**: PostgreSQL with Drizzle ORM for type-safe operations
|
- **Database**: PostgreSQL with Drizzle ORM for type-safe operations
|
||||||
- **Authentication**: NextAuth.js v5 with database sessions and JWT
|
- **Authentication**: Better Auth with database sessions
|
||||||
- **API**: tRPC for end-to-end type-safe client-server communication
|
- **API**: tRPC for end-to-end type-safe client-server communication
|
||||||
- **UI**: Tailwind CSS + shadcn/ui (built on Radix UI primitives)
|
- **UI**: Tailwind CSS + shadcn/ui (built on Radix UI primitives)
|
||||||
- **Storage**: Cloudflare R2 (S3-compatible) for media files
|
- **Storage**: Cloudflare R2 (S3-compatible) for media files
|
||||||
- **Deployment**: Vercel serverless platform with Edge Runtime
|
- **Real-time**: WebSocket with polling fallback for trial execution
|
||||||
- **Package Manager**: Bun exclusively
|
- **Package Manager**: Bun exclusively
|
||||||
- **Real-time**: WebSocket with Edge Runtime compatibility
|
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
@@ -203,14 +202,11 @@ src/
|
|||||||
|
|
||||||
Comprehensive documentation available in the `docs/` folder:
|
Comprehensive documentation available in the `docs/` folder:
|
||||||
|
|
||||||
- **[Quick Reference](docs/quick-reference.md)**: 5-minute setup guide and essential commands
|
- **[Quick Reference](docs/quick-reference.md)**: Essential commands and setup
|
||||||
- **[Project Overview](docs/project-overview.md)**: Complete feature overview and architecture
|
- **[Implementation Guide](docs/implementation-guide.md)**: Technical implementation details
|
||||||
- **[Implementation Details](docs/implementation-details.md)**: Architecture decisions and patterns
|
- **[Project Status](docs/project-status.md)**: Current development state
|
||||||
- **[Database Schema](docs/database-schema.md)**: Complete PostgreSQL schema documentation
|
- **[NAO6 Integration](docs/nao6-quick-reference.md)**: Robot setup and commands
|
||||||
- **[API Routes](docs/api-routes.md)**: Comprehensive tRPC API reference
|
- **[Archive](docs/_archive/)**: Historical documentation (outdated)
|
||||||
- **[Core Blocks System](docs/core-blocks-system.md)**: Repository-based block architecture
|
|
||||||
- **[Plugin System](docs/plugin-system-implementation-guide.md)**: Robot integration guide
|
|
||||||
- **[Project Status](docs/project-status.md)**: Current completion status (98% complete)
|
|
||||||
|
|
||||||
## Research Paper
|
## Research Paper
|
||||||
|
|
||||||
@@ -234,19 +230,39 @@ Full paper available at: [docs/paper.md](docs/paper.md)
|
|||||||
- **4 User Roles**: Complete role-based access control
|
- **4 User Roles**: Complete role-based access control
|
||||||
- **Plugin System**: Extensible robot integration architecture
|
- **Plugin System**: Extensible robot integration architecture
|
||||||
- **Trial System**: Unified design with real-time execution capabilities
|
- **Trial System**: Unified design with real-time execution capabilities
|
||||||
|
- **WebSocket Ready**: Real-time trial updates with polling fallback
|
||||||
|
- **Docker Integration**: NAO6 deployment via docker-compose
|
||||||
|
- **Conditional Branching**: Experiment flow with wizard choices and convergence paths
|
||||||
|
|
||||||
## NAO6 Robot Integration
|
## NAO6 Robot Integration
|
||||||
|
|
||||||
Complete NAO6 robot integration is available in the separate **[nao6-hristudio-integration](../nao6-hristudio-integration/)** repository.
|
Complete NAO6 robot integration is available in the separate **[nao6-hristudio-integration](../nao6-hristudio-integration/)** repository.
|
||||||
|
|
||||||
### Features
|
### Features
|
||||||
- Complete ROS2 driver integration for NAO V6.0
|
- Complete ROS2 Humble driver integration for NAO V6.0
|
||||||
|
- Docker-based deployment with three services: nao_driver, ros_bridge, ros_api
|
||||||
- WebSocket communication via rosbridge
|
- WebSocket communication via rosbridge
|
||||||
- 9 robot actions: speech, movement, gestures, sensors, LEDs
|
- 14 robot actions: speech, movement, gestures, sensors, LEDs, animations
|
||||||
- Real-time control from wizard interface
|
- Real-time control from wizard interface
|
||||||
- Production-ready with NAOqi 2.8.7.4
|
- Production-ready with NAOqi 2.8.7.4, ROS2 Humble
|
||||||
|
|
||||||
### Quick Start
|
### Docker Deployment
|
||||||
|
```bash
|
||||||
|
# Start NAO integration
|
||||||
|
cd nao6-hristudio-integration
|
||||||
|
docker compose up -d
|
||||||
|
|
||||||
|
# Start HRIStudio
|
||||||
|
cd ~/Documents/Projects/hristudio
|
||||||
|
bun dev
|
||||||
|
|
||||||
|
# Access
|
||||||
|
# - HRIStudio: http://localhost:3000
|
||||||
|
# - Test page: http://localhost:3000/nao-test
|
||||||
|
# - rosbridge: ws://localhost:9090
|
||||||
|
```
|
||||||
|
|
||||||
|
### Quick Start Commands
|
||||||
```bash
|
```bash
|
||||||
# Start NAO integration
|
# Start NAO integration
|
||||||
cd ~/naoqi_ros2_ws
|
cd ~/naoqi_ros2_ws
|
||||||
|
|||||||
436
docs/README.md
436
docs/README.md
@@ -1,307 +1,171 @@
|
|||||||
# HRIStudio Documentation
|
# 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**
|
## Getting Started
|
||||||
|
|
||||||
**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)**
|
|
||||||
|
|
||||||
|
### 1. Clone & Install
|
||||||
```bash
|
```bash
|
||||||
# Clone and install
|
git clone https://github.com/soconnor0919/hristudio.git
|
||||||
git clone <repo-url> hristudio
|
|
||||||
cd hristudio
|
cd hristudio
|
||||||
|
git submodule update --init --recursive
|
||||||
bun install
|
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
|
- **Hierarchical Structure**: Study → Experiment → Trial → Step → Action
|
||||||
- **Visual Experiment Designer**: Repository-based plugin architecture with 26 core blocks
|
- **Visual Designer**: 26+ core blocks (events, wizard actions, control flow, observation)
|
||||||
- **Core Block Categories**: Events, wizard actions, control flow, observation blocks
|
- **Conditional Branching**: Wizard choices with convergence paths
|
||||||
- **Real-time Trial Execution**: Live wizard control with data capture
|
- **WebSocket Real-time**: Trial updates with auto-reconnect
|
||||||
- **Multi-role Collaboration**: Administrator, Researcher, Wizard, Observer
|
- **Plugin System**: Robot-agnostic via identifier lookup
|
||||||
- **Comprehensive Data Management**: Synchronized multi-modal capture
|
- **Docker NAO6**: Three-service ROS2 integration
|
||||||
|
|
||||||
### **Technical Excellence**
|
## System Components
|
||||||
- **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**
|
### Backend (src/server/)
|
||||||
- **Unified Components**: Significant reduction in code duplication
|
- `api/routers/` - 12 tRPC routers
|
||||||
- **Panel Architecture**: 90% code sharing between experiment designer and wizard interface
|
- `db/schema.ts` - Drizzle schema (31 tables)
|
||||||
- **Consolidated Wizard**: 3-panel design with trial controls, horizontal timeline, and unified robot controls
|
- `services/trial-execution.ts` - Trial execution engine
|
||||||
- **Enterprise DataTables**: Advanced filtering, export, pagination
|
- `services/websocket-manager.ts` - Real-time connections
|
||||||
- **Comprehensive Testing**: Realistic seed data with complete scenarios
|
|
||||||
- **Developer Friendly**: Clear patterns and extensive documentation
|
|
||||||
|
|
||||||
### **Robot Integration**
|
### Frontend (src/)
|
||||||
- **NAO6 Full Support**: Complete ROS2 integration with movement, speech, and sensor control
|
- `app/` - Next.js App Router pages
|
||||||
- **Real-time Control**: WebSocket-based robot control through web interface
|
- `components/trials/wizard/` - Wizard interface
|
||||||
- **Safety Features**: Emergency stops, movement limits, and comprehensive monitoring
|
- `hooks/useWebSocket.ts` - Real-time trial updates
|
||||||
- **Production Ready**: Tested with NAO V6.0 / NAOqi 2.8.7.4 / ROS2 Humble
|
- `lib/ros/wizard-ros-service.ts` - Robot control
|
||||||
- **Troubleshooting Guides**: Complete documentation for setup and problem resolution
|
|
||||||
|
## 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**
|
**Last Updated**: March 22, 2026
|
||||||
|
|
||||||
**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.
|
|
||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
## Overview
|
## 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
|
## Table of Contents
|
||||||
|
|
||||||
@@ -25,7 +25,14 @@ This guide provides step-by-step technical instructions for implementing HRIStud
|
|||||||
### 1. Initialize Project
|
### 1. Initialize Project
|
||||||
|
|
||||||
```bash
|
```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 \
|
bunx create-t3-app@latest hristudio \
|
||||||
--nextjs \
|
--nextjs \
|
||||||
--tailwind \
|
--tailwind \
|
||||||
|
|||||||
@@ -27,10 +27,15 @@ bun dev
|
|||||||
|
|
||||||
| Service | Port | Description |
|
| Service | Port | Description |
|
||||||
|---------|------|-------------|
|
|---------|------|-------------|
|
||||||
| nao_driver | - | NAOqi driver node |
|
| nao_driver | - | NAOqi driver + robot init |
|
||||||
| ros_bridge | 9090 | WebSocket bridge |
|
| ros_bridge | 9090 | WebSocket bridge |
|
||||||
| ros_api | - | ROS API services |
|
| 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
|
## ROS Topics
|
||||||
|
|
||||||
**Commands (Publish to these):**
|
**Commands (Publish to these):**
|
||||||
@@ -52,6 +57,21 @@ bun dev
|
|||||||
/info - Robot info
|
/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
|
## Manual Control
|
||||||
|
|
||||||
### Test Connectivity
|
### Test Connectivity
|
||||||
|
|||||||
@@ -1,402 +1,189 @@
|
|||||||
# HRIStudio Project Status
|
# HRIStudio Project Status
|
||||||
|
|
||||||
## 🎯 **Current Status: Production Ready**
|
## Current Status: Active Development
|
||||||
|
|
||||||
**Project Version**: 1.0.0
|
**Project Version**: 1.0.0
|
||||||
**Last Updated**: December 2024
|
**Last Updated**: March 2026
|
||||||
**Overall Completion**: Complete ✅
|
**Overall Completion**: 98%
|
||||||
**Status**: Ready for Production Deployment
|
**Status**: Thesis research phase
|
||||||
|
|
||||||
### **🎉 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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📊 **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**
|
### Recent Updates (March 2026)
|
||||||
- ✅ **Complete Backend Infrastructure** - Full API with 12 tRPC routers
|
- ✅ WebSocket real-time trial updates implemented
|
||||||
- ✅ **Complete Frontend Implementation** - Professional UI with unified experiences
|
- ✅ Better Auth migration complete (replaced NextAuth.js)
|
||||||
- ✅ **Full Type Safety** - Zero TypeScript errors in production code
|
- ✅ Docker integration for NAO6 (3 services: nao_driver, ros_bridge, ros_api)
|
||||||
- ✅ **Complete Authentication** - Role-based access control system
|
- ✅ Conditional branching with wizard choices and convergence
|
||||||
- ✅ **Visual Experiment Designer** - Repository-based plugin architecture
|
- ✅ 14 NAO6 robot actions (speech, movement, gestures, sensors, LEDs, animations)
|
||||||
- ✅ **Core Blocks System** - 26 blocks across 4 categories (events, wizard, control, observation)
|
- ✅ Plugin identifier system for clean plugin lookup
|
||||||
- ✅ **Production Database** - 31 tables with comprehensive relationships
|
- ✅ Seed script with branching experiment structure
|
||||||
- ✅ **Development Environment** - Realistic seed data and testing scenarios
|
|
||||||
- ✅ **Trial System Overhaul** - Unified EntityView patterns with real-time execution
|
### Key Achievements
|
||||||
- ✅ **WebSocket Integration** - Real-time updates with polling fallback
|
- ✅ Complete backend with 12 tRPC routers
|
||||||
- ✅ **Route Consolidation** - Study-scoped architecture with eliminated duplicate components
|
- ✅ Professional UI with unified experiences
|
||||||
- ✅ **Multi-View Trial Interface** - Role-based Wizard, Observer, and Participant views for thesis research
|
- ✅ Full TypeScript coverage (strict mode)
|
||||||
- ✅ **Dashboard Resolution** - Fixed routing issues and implemented proper layout structure
|
- ✅ 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
|
│ User Interface Layer │
|
||||||
- **Repository Management**: Admin tools for plugin repositories and trust levels
|
│ ├── Experiment Designer (visual programming) │
|
||||||
- **Plugin Store**: Study-scoped plugin installation and configuration
|
│ ├── Wizard Interface (trial execution) │
|
||||||
- **Block Categories**: Events, wizard actions, control flow, observation blocks
|
│ ├── Observer View (live monitoring) │
|
||||||
- **Type Safety**: Full TypeScript support for all plugin definitions
|
│ └── Participant View (thesis study) │
|
||||||
- **Documentation**: Complete guides for core blocks and robot plugins
|
├─────────────────────────────────────────────────────┤
|
||||||
|
│ Data Management Layer │
|
||||||
|
│ ├── PostgreSQL + Drizzle ORM │
|
||||||
**Database Schema**
|
│ ├── tRPC API (12 routers) │
|
||||||
- ✅ 31 tables covering all research workflows
|
│ └── Better Auth (role-based auth) │
|
||||||
- ✅ Complete relationships with foreign keys and indexes
|
├─────────────────────────────────────────────────────┤
|
||||||
- ✅ Audit logging and soft deletes implemented
|
│ Robot Integration Layer │
|
||||||
- ✅ Performance optimizations with strategic indexing
|
│ ├── Plugin system (robot-agnostic) │
|
||||||
- ✅ JSONB support for flexible metadata storage
|
│ ├── ROS2 via rosbridge WebSocket │
|
||||||
|
│ └── Docker deployment (nao_driver, ros_bridge) │
|
||||||
**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[];
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### **Key Fixes Applied**
|
### Plugin Identifier System
|
||||||
- ✅ **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
|
plugins table:
|
||||||
- ✅ **State Management**: Zustand store working correctly with all actions
|
- id: UUID (primary key)
|
||||||
- ✅ **UI Layout**: Three-panel layout with Action Library, Step Flow, and Properties
|
- 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)**
|
Experiment steps support conditional branching with wizard choices:
|
||||||
**Theme**: Production Deployment Preparation
|
|
||||||
|
|
||||||
**Goals**:
|
```
|
||||||
1. ✅ Complete experiment designer redesign
|
Step 3 (Comprehension Check)
|
||||||
2. ✅ Fix step addition functionality
|
└── wizard_wait_for_response
|
||||||
3. ✅ Resolve TypeScript compilation issues
|
├── Click "Correct" → setLastResponse("Correct") → nextStepId=step4a
|
||||||
4. ⏳ Final code quality improvements
|
└── Click "Incorrect" → setLastResponse("Incorrect") → nextStepId=step4b
|
||||||
|
|
||||||
**Sprint Metrics**:
|
Step 4a/4b (Branches)
|
||||||
- **Story Points**: 34 total
|
└── conditions.nextStepId: step5.id → convergence point
|
||||||
- **Completed**: 30 points
|
|
||||||
- **In Progress**: 4 points
|
|
||||||
- **Planned**: 0 points
|
|
||||||
|
|
||||||
### **Development Velocity**
|
Step 5 (Story Continues)
|
||||||
- **Sprint 1**: 28 story points completed
|
└── Linear progression to Step 6
|
||||||
- **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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🎯 **Success Criteria Validation**
|
## NAO6 Robot Actions (14 total)
|
||||||
|
|
||||||
### **Technical Requirements** ✅ **Met**
|
| Category | Actions |
|
||||||
- ✅ End-to-end type safety throughout platform
|
|----------|---------|
|
||||||
- ✅ Role-based access control with 4 distinct roles
|
| Speech | say, say_with_emotion, wave_goodbye |
|
||||||
- ✅ Comprehensive API covering all research workflows
|
| Movement | walk, turn, move_to_posture |
|
||||||
- ✅ Visual experiment designer with drag-and-drop interface
|
| Gestures | play_animation, gesture |
|
||||||
- ✅ Real-time trial execution framework ready
|
| Sensors | get_sensors, bumper_state, touch_state |
|
||||||
- ✅ Scalable architecture built for research teams
|
| LEDs | set_eye_leds, set_breathing_lights |
|
||||||
|
|
||||||
### **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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🚀 **Production Readiness**
|
## Tech Stack
|
||||||
|
|
||||||
### **Deployment Checklist** ✅ **Complete**
|
| Component | Technology | Version |
|
||||||
- ✅ Environment variables configured for Vercel
|
|-----------|------------|---------|
|
||||||
- ✅ Database migrations ready for production
|
| Framework | Next.js | 15-16.x |
|
||||||
- ✅ Security headers and CSRF protection configured
|
| Language | TypeScript | 5.x (strict) |
|
||||||
- ✅ Error tracking and performance monitoring setup
|
| Database | PostgreSQL | 14+ |
|
||||||
- ✅ Build process optimized for Edge Runtime
|
| ORM | Drizzle | latest |
|
||||||
- ✅ Static assets and CDN configuration ready
|
| Auth | NextAuth.js | v5 |
|
||||||
|
| API | tRPC | latest |
|
||||||
### **Performance Validation** ✅ **Passed**
|
| UI | Tailwind + shadcn/ui | latest |
|
||||||
- ✅ Page load time < 2 seconds (Currently optimal)
|
| Real-time | WebSocket | with polling fallback |
|
||||||
- ✅ API response time < 200ms (Currently optimal)
|
| Robot | ROS2 Humble | via rosbridge |
|
||||||
- ✅ Database query time < 50ms (Currently optimal)
|
| Package Manager | Bun | latest |
|
||||||
- ✅ 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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📈 **Platform Capabilities**
|
## Development Status
|
||||||
|
|
||||||
### **Research Workflow Support**
|
### Completed Features
|
||||||
- **Study Management**: Complete lifecycle from creation to analysis
|
| Feature | Status | Notes |
|
||||||
- **Team Collaboration**: Multi-user support with role-based permissions
|
|---------|--------|-------|
|
||||||
- **Experiment Design**: Visual programming interface for protocol creation
|
| Database Schema | ✅ | 31 tables |
|
||||||
- **Trial Execution**: Panel-based wizard interface matching experiment designer architecture
|
| Authentication | ✅ | 4 roles |
|
||||||
- **Real-time Updates**: WebSocket integration with intelligent polling fallback
|
| Experiment Designer | ✅ | 26+ blocks |
|
||||||
- **Data Capture**: Synchronized multi-modal data streams with comprehensive event logging
|
| Wizard Interface | ✅ | 3-panel design |
|
||||||
- **Robot Integration**: Plugin-based support for multiple platforms
|
| Real-time Updates | ✅ | WebSocket |
|
||||||
|
| Plugin System | ✅ | Robot-agnostic |
|
||||||
|
| NAO6 Integration | ✅ | Docker deployment |
|
||||||
|
| Conditional Branching | ✅ | Wizard choices |
|
||||||
|
| Mock Robot | ✅ | Development mode |
|
||||||
|
|
||||||
### **Technical Capabilities**
|
### Known Issues
|
||||||
- **Scalability**: Architecture supporting large research institutions
|
| Issue | Status | Notes |
|
||||||
- **Performance**: Optimized for concurrent multi-user environments
|
|-------|--------|-------|
|
||||||
- **Security**: Research-grade data protection and access control
|
| robots.executeSystemAction | Known error | Fallback works |
|
||||||
- **Flexibility**: Customizable workflows for diverse methodologies
|
|
||||||
- **Integration**: Robot platform agnostic with plugin architecture
|
|
||||||
- **Compliance**: Research ethics and data protection compliance
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔮 **Roadmap & Future Work**
|
## SSH Deployment Commands
|
||||||
|
|
||||||
### **Immediate Priorities** (Next 30 days)
|
```bash
|
||||||
- **Wizard Interface Development** - Complete rebuild of trial execution interface
|
# Local development
|
||||||
- **Robot Control Implementation** - NAO6 integration with WebSocket communication
|
bun dev
|
||||||
- **Trial Execution Engine** - Step-by-step protocol execution with real-time data capture
|
|
||||||
- **User Experience Testing** - Validate study-scoped workflows with target users
|
|
||||||
|
|
||||||
### **Short-term Goals** (Next 60 days)
|
# Database
|
||||||
- **IRB Application Preparation** - Complete documentation and study protocols
|
bun db:push # Push schema changes
|
||||||
- **Reference Experiment Implementation** - Well-documented HRI experiment for comparison study
|
bun db:seed # Seed with test data
|
||||||
- **Training Materials Development** - Comprehensive materials for both HRIStudio and Choregraphe
|
bun run docker:up # Start PostgreSQL
|
||||||
- **Platform Validation** - Extensive testing and reliability verification
|
|
||||||
|
|
||||||
### **Long-term Vision** (Next 90+ days)
|
# Quality
|
||||||
- **User Study Execution** - Comparative study with 10-12 non-engineering participants
|
bun typecheck # TypeScript validation
|
||||||
- **Thesis Research Completion** - Data analysis and academic paper preparation
|
bun lint # ESLint
|
||||||
- **Platform Refinement** - Post-study improvements based on real user feedback
|
```
|
||||||
- **Community Release** - Open source release for broader HRI research community
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🎊 **Project Success Declaration**
|
## Thesis Timeline
|
||||||
|
|
||||||
**HRIStudio is officially ready for production deployment.**
|
Current phase: **March 2026** - Implementation complete, preparing user study
|
||||||
|
|
||||||
### **Completion Summary**
|
| Phase | Status | Date |
|
||||||
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.
|
|-------|--------|------|
|
||||||
|
| Proposal | ✅ | Sept 2025 |
|
||||||
### **Key Success Metrics**
|
| IRB Application | ✅ | Dec 2025 |
|
||||||
- **Development Velocity**: Consistently meeting sprint goals with 30+ story points
|
| Implementation | ✅ | Feb 2026 |
|
||||||
- **Code Quality**: Zero production TypeScript errors, fully functional designer
|
| User Study | 🔄 In Progress | Mar-Apr 2026 |
|
||||||
- **Architecture Quality**: Clean study-scoped hierarchy with eliminated code duplication
|
| Defense | Scheduled | April 2026 |
|
||||||
- **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.**
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔧 **Development Notes**
|
## Next Steps
|
||||||
|
|
||||||
### **Technical Debt Status**
|
1. Complete user study (10-12 participants)
|
||||||
- **High Priority**: None identified
|
2. Data analysis and thesis writing
|
||||||
- **Medium Priority**: Minor database query optimizations possible
|
3. Final defense April 2026
|
||||||
- **Low Priority**: Some older components could benefit from modern React patterns
|
4. Open source release
|
||||||
|
|
||||||
### **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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
*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
|
\hline
|
||||||
September & Finalize and submit this proposal (Due: Sept. 20).
|
September & Finalize and submit this proposal (Due: Sept. 20).
|
||||||
|
|
||||||
Submit IRB application for the user study. \\
|
Submit IRB application for the study. \\
|
||||||
\hline
|
\hline
|
||||||
Oct -- Nov & Complete final implementation of core HRIStudio features.
|
Oct -- Nov & Complete final implementation of core HRIStudio features.
|
||||||
|
|
||||||
@@ -119,13 +119,15 @@ Begin recruiting participants. \\
|
|||||||
\hline
|
\hline
|
||||||
\multicolumn{2}{|l|}{\textbf{Spring 2026: Execution, Analysis, and Writing}} \\
|
\multicolumn{2}{|l|}{\textbf{Spring 2026: Execution, Analysis, and Writing}} \\
|
||||||
\hline
|
\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
|
\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
|
\hline
|
||||||
April & Submit completed thesis draft to the defense committee (Due: April 1).
|
April & Submit completed thesis draft to the defense committee (Due: April 1).
|
||||||
|
|
||||||
|
|||||||
@@ -1,67 +1,30 @@
|
|||||||
# HRIStudio Quick Reference Guide
|
# 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
|
```bash
|
||||||
# Clone and install
|
# Clone with submodules
|
||||||
git clone <repo-url> hristudio
|
git clone https://github.com/soconnor0919/hristudio.git
|
||||||
cd hristudio
|
cd hristudio
|
||||||
|
git submodule update --init --recursive
|
||||||
|
|
||||||
|
# Install and setup
|
||||||
bun install
|
bun install
|
||||||
|
|
||||||
# Start database
|
|
||||||
bun run docker:up
|
bun run docker:up
|
||||||
|
|
||||||
# Setup database
|
|
||||||
bun db:push
|
bun db:push
|
||||||
bun db:seed
|
bun db:seed
|
||||||
|
|
||||||
# Single command now syncs all repositories:
|
# Start
|
||||||
# - Core blocks from localhost:3000/hristudio-core
|
|
||||||
# - Robot plugins from https://repo.hristudio.com
|
|
||||||
|
|
||||||
# Start development
|
|
||||||
bun dev
|
bun dev
|
||||||
```
|
```
|
||||||
|
|
||||||
### Default Login
|
**Login**: `sean@soconnor.dev` / `password123`
|
||||||
- **Admin**: `sean@soconnor.dev` / `password123`
|
|
||||||
- **Researcher**: `alice.rodriguez@university.edu` / `password123`
|
|
||||||
- **Wizard**: `emily.watson@lab.edu` / `password123`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📁 **Project Structure**
|
## Key Concepts
|
||||||
|
|
||||||
```
|
### Hierarchy
|
||||||
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
|
|
||||||
```
|
```
|
||||||
Study → Experiment → Trial → Step → Action
|
Study → Experiment → Trial → Step → Action
|
||||||
```
|
```
|
||||||
@@ -70,530 +33,117 @@ Study → Experiment → Trial → Step → Action
|
|||||||
- **Administrator**: Full system access
|
- **Administrator**: Full system access
|
||||||
- **Researcher**: Create studies, design experiments
|
- **Researcher**: Create studies, design experiments
|
||||||
- **Wizard**: Execute trials, control robots
|
- **Wizard**: Execute trials, control robots
|
||||||
- **Observer**: Read-only access
|
- **Observer**: Read-only monitoring
|
||||||
|
|
||||||
### Core Workflows
|
### Plugin Identifier System
|
||||||
1. **Study Creation** → Team setup → Participant recruitment
|
- `identifier`: Machine-readable key (e.g., `nao6-ros2`)
|
||||||
2. **Experiment Design** → Visual designer → Protocol validation
|
- `name`: Display name (e.g., `NAO6 Robot (ROS2 Integration)`)
|
||||||
3. **Trial Execution** → Wizard interface → Data capture
|
- Lookup order: identifier → name → fallback
|
||||||
4. **Data Analysis** → Export → Insights
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🛠 **Development Commands**
|
## Development Commands
|
||||||
|
|
||||||
| Command | Purpose |
|
| Command | Description |
|
||||||
|---------|---------|
|
|---------|-------------|
|
||||||
| `bun dev` | Start development server |
|
| `bun dev` | Start dev server |
|
||||||
| `bun build` | Build for production |
|
| `bun build` | Production build |
|
||||||
| `bun typecheck` | TypeScript validation |
|
| `bun typecheck` | TypeScript validation |
|
||||||
| `bun lint` | Code quality checks |
|
|
||||||
| `bun db:push` | Push schema changes |
|
| `bun db:push` | Push schema changes |
|
||||||
| `bun db:seed` | Seed data & sync repositories |
|
| `bun db:seed` | Seed data + sync plugins |
|
||||||
| `bun db:studio` | Open database GUI |
|
| `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
|
```bash
|
||||||
cd ~/Documents/Projects/nao6-hristudio-integration
|
cd ~/Documents/Projects/nao6-hristudio-integration
|
||||||
docker compose up -d
|
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
|
│ UI: Design / Execute / Playback │
|
||||||
/joint_angles - Joint position control
|
├─────────────────────────────────────┤
|
||||||
/camera/front/image_raw
|
│ Server: tRPC, Auth, Trial Logic │
|
||||||
/camera/bottom/image_raw
|
├─────────────────────────────────────┤
|
||||||
/imu/torso
|
│ Data: PostgreSQL, File Storage │
|
||||||
/bumper
|
│ Robot: ROS2 via WebSocket │
|
||||||
/{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();
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🗄️ **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
|
### Core Tables
|
||||||
```sql
|
- `users` - Authentication
|
||||||
users -- Authentication & profiles
|
- `studies` - Research projects
|
||||||
studies -- Research projects
|
- `experiments` - Protocol templates
|
||||||
experiments -- Protocol templates
|
- `trials` - Execution instances
|
||||||
participants -- Study participants
|
- `steps` - Experiment phases
|
||||||
trials -- Experiment instances
|
- `actions` - Atomic tasks
|
||||||
steps -- Experiment phases
|
- `plugins` - Robot integrations (identifier column)
|
||||||
trial_events -- Execution logs
|
- `trial_events` - Execution logs
|
||||||
robots -- Available platforms
|
|
||||||
```
|
---
|
||||||
|
|
||||||
|
## Route Structure
|
||||||
|
|
||||||
### Key Relationships
|
|
||||||
```
|
```
|
||||||
studies → experiments → trials
|
/dashboard - Global overview
|
||||||
studies → participants
|
/studies - Study list
|
||||||
trials → trial_events
|
/studies/[id] - Study details
|
||||||
experiments → steps
|
/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
|
```typescript
|
||||||
// Page wrapper with navigation
|
// Loading a plugin by identifier
|
||||||
<PageLayout title="Studies" description="Manage research studies">
|
const plugin = await trialExecution.loadPlugin("nao6-ros2");
|
||||||
<StudiesTable />
|
|
||||||
</PageLayout>
|
|
||||||
|
|
||||||
// Entity forms (unified pattern)
|
// Action execution
|
||||||
<EntityForm
|
await robot.execute("nao6-ros2.say_with_emotion", { text: "Hello" });
|
||||||
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}`);
|
|
||||||
};
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🎯 **Route Structure**
|
Last updated: March 2026
|
||||||
|
|
||||||
### 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.*
|
|
||||||
Submodule robot-plugins updated: ff48567918...d772aecc54
Reference in New Issue
Block a user