diff --git a/README.md b/README.md index b4374ef..d991a2a 100644 --- a/README.md +++ b/README.md @@ -64,16 +64,15 @@ bun dev ## 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 - **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 - **UI**: Tailwind CSS + shadcn/ui (built on Radix UI primitives) - **Storage**: Cloudflare R2 (S3-compatible) for media files -- **Deployment**: Vercel serverless platform with Edge Runtime +- **Real-time**: WebSocket with polling fallback for trial execution - **Package Manager**: Bun exclusively -- **Real-time**: WebSocket with Edge Runtime compatibility ## Architecture @@ -203,14 +202,11 @@ src/ Comprehensive documentation available in the `docs/` folder: -- **[Quick Reference](docs/quick-reference.md)**: 5-minute setup guide and essential commands -- **[Project Overview](docs/project-overview.md)**: Complete feature overview and architecture -- **[Implementation Details](docs/implementation-details.md)**: Architecture decisions and patterns -- **[Database Schema](docs/database-schema.md)**: Complete PostgreSQL schema documentation -- **[API Routes](docs/api-routes.md)**: Comprehensive tRPC API reference -- **[Core Blocks System](docs/core-blocks-system.md)**: Repository-based block architecture -- **[Plugin System](docs/plugin-system-implementation-guide.md)**: Robot integration guide -- **[Project Status](docs/project-status.md)**: Current completion status (98% complete) +- **[Quick Reference](docs/quick-reference.md)**: Essential commands and setup +- **[Implementation Guide](docs/implementation-guide.md)**: Technical implementation details +- **[Project Status](docs/project-status.md)**: Current development state +- **[NAO6 Integration](docs/nao6-quick-reference.md)**: Robot setup and commands +- **[Archive](docs/_archive/)**: Historical documentation (outdated) ## Research Paper @@ -234,19 +230,39 @@ Full paper available at: [docs/paper.md](docs/paper.md) - **4 User Roles**: Complete role-based access control - **Plugin System**: Extensible robot integration architecture - **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 Complete NAO6 robot integration is available in the separate **[nao6-hristudio-integration](../nao6-hristudio-integration/)** repository. ### 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 -- 9 robot actions: speech, movement, gestures, sensors, LEDs +- 14 robot actions: speech, movement, gestures, sensors, LEDs, animations - 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 # Start NAO integration cd ~/naoqi_ros2_ws diff --git a/DOCUMENTATION.md b/_archive/DOCUMENTATION.md similarity index 100% rename from DOCUMENTATION.md rename to _archive/DOCUMENTATION.md diff --git a/HANDOFF-NAO6-INTEGRATION.md b/_archive/HANDOFF-NAO6-INTEGRATION.md similarity index 100% rename from HANDOFF-NAO6-INTEGRATION.md rename to _archive/HANDOFF-NAO6-INTEGRATION.md diff --git a/THESIS_PROJECT_BACKLOG.md b/_archive/THESIS_PROJECT_BACKLOG.md similarity index 100% rename from THESIS_PROJECT_BACKLOG.md rename to _archive/THESIS_PROJECT_BACKLOG.md diff --git a/TRIAL_START_DEBUG.md b/_archive/TRIAL_START_DEBUG.md similarity index 100% rename from TRIAL_START_DEBUG.md rename to _archive/TRIAL_START_DEBUG.md diff --git a/WIZARD_INTERFACE_README.md b/_archive/WIZARD_INTERFACE_README.md similarity index 100% rename from WIZARD_INTERFACE_README.md rename to _archive/WIZARD_INTERFACE_README.md diff --git a/errors.txt b/_archive/errors.txt similarity index 100% rename from errors.txt rename to _archive/errors.txt diff --git a/nao6_integration_README.md b/_archive/nao6_integration_README.md similarity index 100% rename from nao6_integration_README.md rename to _archive/nao6_integration_README.md diff --git a/plugin_dump.json b/_archive/plugin_dump.json similarity index 100% rename from plugin_dump.json rename to _archive/plugin_dump.json diff --git a/public/simple-ws-test.html b/_archive/simple-ws-test.html similarity index 100% rename from public/simple-ws-test.html rename to _archive/simple-ws-test.html diff --git a/public/test-websocket.html b/_archive/test-websocket.html similarity index 100% rename from public/test-websocket.html rename to _archive/test-websocket.html diff --git a/public/ws-check.html b/_archive/ws-check.html similarity index 100% rename from public/ws-check.html rename to _archive/ws-check.html diff --git a/docs/README.md b/docs/README.md index 234ff0b..043a9cc 100755 --- a/docs/README.md +++ b/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 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. \ No newline at end of file +**Last Updated**: March 22, 2026 \ No newline at end of file diff --git a/docs/MARCH-2026-SESSION.md b/docs/_archive/MARCH-2026-SESSION.md similarity index 100% rename from docs/MARCH-2026-SESSION.md rename to docs/_archive/MARCH-2026-SESSION.md diff --git a/docs/api-routes.md b/docs/_archive/api-routes.md similarity index 100% rename from docs/api-routes.md rename to docs/_archive/api-routes.md diff --git a/docs/block-designer-implementation.md b/docs/_archive/block-designer-implementation.md similarity index 100% rename from docs/block-designer-implementation.md rename to docs/_archive/block-designer-implementation.md diff --git a/docs/block-designer.md b/docs/_archive/block-designer.md similarity index 100% rename from docs/block-designer.md rename to docs/_archive/block-designer.md diff --git a/docs/cleanup-summary.md b/docs/_archive/cleanup-summary.md similarity index 100% rename from docs/cleanup-summary.md rename to docs/_archive/cleanup-summary.md diff --git a/docs/core-blocks-system.md b/docs/_archive/core-blocks-system.md similarity index 100% rename from docs/core-blocks-system.md rename to docs/_archive/core-blocks-system.md diff --git a/docs/database-schema.md b/docs/_archive/database-schema.md similarity index 100% rename from docs/database-schema.md rename to docs/_archive/database-schema.md diff --git a/docs/deployment-operations.md b/docs/_archive/deployment-operations.md similarity index 100% rename from docs/deployment-operations.md rename to docs/_archive/deployment-operations.md diff --git a/docs/experiment-designer-redesign.md b/docs/_archive/experiment-designer-redesign.md similarity index 100% rename from docs/experiment-designer-redesign.md rename to docs/_archive/experiment-designer-redesign.md diff --git a/docs/experiment-designer-step-integration.md b/docs/_archive/experiment-designer-step-integration.md similarity index 100% rename from docs/experiment-designer-step-integration.md rename to docs/_archive/experiment-designer-step-integration.md diff --git a/docs/feature-requirements.md b/docs/_archive/feature-requirements.md similarity index 100% rename from docs/feature-requirements.md rename to docs/_archive/feature-requirements.md diff --git a/docs/flow-designer-connections.md b/docs/_archive/flow-designer-connections.md similarity index 100% rename from docs/flow-designer-connections.md rename to docs/_archive/flow-designer-connections.md diff --git a/docs/implementation-details.md b/docs/_archive/implementation-details.md similarity index 100% rename from docs/implementation-details.md rename to docs/_archive/implementation-details.md diff --git a/docs/paper.md b/docs/_archive/paper.md similarity index 100% rename from docs/paper.md rename to docs/_archive/paper.md diff --git a/docs/plugin-system-implementation-guide.md b/docs/_archive/plugin-system-implementation-guide.md similarity index 100% rename from docs/plugin-system-implementation-guide.md rename to docs/_archive/plugin-system-implementation-guide.md diff --git a/docs/project-overview.md b/docs/_archive/project-overview.md similarity index 100% rename from docs/project-overview.md rename to docs/_archive/project-overview.md diff --git a/docs/roman-2025-talk.md b/docs/_archive/roman-2025-talk.md similarity index 100% rename from docs/roman-2025-talk.md rename to docs/_archive/roman-2025-talk.md diff --git a/docs/ros2-integration.md b/docs/_archive/ros2-integration.md similarity index 100% rename from docs/ros2-integration.md rename to docs/_archive/ros2-integration.md diff --git a/docs/ros2_naoqi.md b/docs/_archive/ros2_naoqi.md similarity index 100% rename from docs/ros2_naoqi.md rename to docs/_archive/ros2_naoqi.md diff --git a/docs/route-consolidation-summary.md b/docs/_archive/route-consolidation-summary.md similarity index 100% rename from docs/route-consolidation-summary.md rename to docs/_archive/route-consolidation-summary.md diff --git a/docs/thesis-project-priorities.md b/docs/_archive/thesis-project-priorities.md similarity index 100% rename from docs/thesis-project-priorities.md rename to docs/_archive/thesis-project-priorities.md diff --git a/docs/trial-system-overhaul.md b/docs/_archive/trial-system-overhaul.md similarity index 100% rename from docs/trial-system-overhaul.md rename to docs/_archive/trial-system-overhaul.md diff --git a/docs/wizard-interface-final.md b/docs/_archive/wizard-interface-final.md similarity index 100% rename from docs/wizard-interface-final.md rename to docs/_archive/wizard-interface-final.md diff --git a/docs/wizard-interface-guide.md b/docs/_archive/wizard-interface-guide.md similarity index 100% rename from docs/wizard-interface-guide.md rename to docs/_archive/wizard-interface-guide.md diff --git a/docs/wizard-interface-redesign.md b/docs/_archive/wizard-interface-redesign.md similarity index 100% rename from docs/wizard-interface-redesign.md rename to docs/_archive/wizard-interface-redesign.md diff --git a/docs/wizard-interface-summary.md b/docs/_archive/wizard-interface-summary.md similarity index 100% rename from docs/wizard-interface-summary.md rename to docs/_archive/wizard-interface-summary.md diff --git a/docs/work_in_progress.md b/docs/_archive/work_in_progress.md similarity index 100% rename from docs/work_in_progress.md rename to docs/_archive/work_in_progress.md diff --git a/docs/implementation-guide.md b/docs/implementation-guide.md index 001641f..9405396 100755 --- a/docs/implementation-guide.md +++ b/docs/implementation-guide.md @@ -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 \ diff --git a/docs/nao6-quick-reference.md b/docs/nao6-quick-reference.md index 6d283df..c59fa37 100755 --- a/docs/nao6-quick-reference.md +++ b/docs/nao6-quick-reference.md @@ -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 diff --git a/docs/project-status.md b/docs/project-status.md index e218b8d..2a70fc2 100755 --- a/docs/project-status.md +++ b/docs/project-status.md @@ -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.* \ No newline at end of file +*Last Updated: March 22, 2026* \ No newline at end of file diff --git a/docs/proposal.tex b/docs/proposal.tex index ef239a7..55c5d5c 100755 --- a/docs/proposal.tex +++ b/docs/proposal.tex @@ -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). diff --git a/docs/quick-reference.md b/docs/quick-reference.md index 1b4ff0d..82e1481 100755 --- a/docs/quick-reference.md +++ b/docs/quick-reference.md @@ -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 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 - - - +// Loading a plugin by identifier +const plugin = await trialExecution.loadPlugin("nao6-ros2"); -// Entity forms (unified pattern) - - -// Data tables (consistent across entities) - -``` - -### Form Patterns -```typescript -// Standard form setup -const form = useForm({ - 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 ; -if (!session) return ; -``` - -### 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 ; -if (error) return ; -return ; -``` - -### 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.* \ No newline at end of file +Last updated: March 2026 \ No newline at end of file diff --git a/robot-plugins b/robot-plugins index ff48567..d772aec 160000 --- a/robot-plugins +++ b/robot-plugins @@ -1 +1 @@ -Subproject commit ff485679181377f208c59a754095784b2ee9ac31 +Subproject commit d772aecc54306b211cd97ff6f720936d38a6b8a9