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

📚 Documentation Overview

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

Core Documents

Project Overview
- Executive summary and project goals
- Core features and system architecture
- User roles and permissions
- Technology stack overview
- Key concepts and success metrics
Database Schema
- Complete PostgreSQL schema with Drizzle ORM
- Table definitions and relationships
- Indexes and performance optimizations
- Views and stored procedures
- Migration guidelines
API Routes
- Comprehensive tRPC route documentation
- Request/response schemas
- Authentication requirements
- WebSocket events
- Rate limiting and error handling
Feature Requirements
- Detailed user stories and acceptance criteria
- Functional requirements by module
- Non-functional requirements
- UI/UX specifications
- Integration requirements
Implementation Guide
- Step-by-step technical implementation
- Code examples and patterns
- Frontend and backend architecture
- Real-time features implementation
- Testing strategies
Deployment & Operations
- Infrastructure requirements
- Vercel deployment strategies
- Monitoring and observability
- Backup and recovery procedures
- Security operations
ROS2 Integration
- rosbridge WebSocket architecture
- Client-side ROS connection management
- Message type definitions
- Robot plugin implementation
- Security considerations for robot communication

🚀 Quick Start for Developers

Prerequisites

Node.js 18+ with Bun package manager
PostgreSQL 15+
Docker and Docker Compose (for local development)
S3-compatible storage (Cloudflare R2 recommended for Vercel)
ROS2 with rosbridge_suite (for robot integration)

Initial Setup

Clone the repository
Copy .env.example to .env.local
Run docker-compose up -d for local services
Run bun install to install dependencies
Run bun db:migrate to set up the database
Run bun dev to start the development server

For AI Agents Building the Application

When implementing HRIStudio, follow this sequence:

Start with Project Setup
- Use the Implementation Guide to set up the project structure
- Follow the rules in rules.txt for coding standards
- Reference the Project Overview for architectural decisions
Implement Database Layer
- Use the Database Schema document to create all tables
- Implement the schema files with Drizzle ORM
- Set up relationships and indexes as specified
Build API Layer
- Follow the API Routes document to implement all tRPC routes
- Ensure proper authentication and authorization
- Implement error handling and validation
Create UI Components
- Reference Feature Requirements for UI specifications
- Use shadcn/ui components exclusively
- Follow the component patterns in Implementation Guide
Add Real-time Features
- Implement WebSocket server for trial execution
- Add real-time updates for wizard interface
- Ensure proper state synchronization
Implement Robot Integration
- Follow ROS2 Integration guide for robot plugins
- Set up rosbridge on robot systems
- Test WebSocket communication
Deploy and Monitor
- Follow Deployment & Operations guide for Vercel
- Set up monitoring and logging
- Implement backup strategies

📋 Key Implementation Notes

Architecture Principles

Modular Design: Each feature is self-contained
Type Safety: Full TypeScript with strict mode
Server-First: Leverage React Server Components
Real-time: WebSocket for live trial execution
Secure: Role-based access control throughout

Technology Choices

Next.js 15: App Router for modern React patterns
tRPC: Type-safe API communication
Drizzle ORM: Type-safe database queries
NextAuth.js v5: Authentication and authorization
shadcn/ui: Consistent UI components
Cloudflare R2: S3-compatible object storage
roslib.js: WebSocket-based ROS2 communication
Vercel KV: Edge-compatible caching (instead of Redis)

Critical Features

Visual Experiment Designer: Drag-and-drop interface
Wizard Interface: Real-time control during trials
Plugin System: Extensible robot platform support
Data Capture: Comprehensive recording of all trial data
Collaboration: Multi-user support with role-based access

🔧 Development Workflow

Code Organization

src/
├── app/           # Next.js app router pages
├── components/    # Reusable UI components
├── features/      # Feature-specific modules
├── lib/          # Core utilities and setup
├── server/       # Server-side code
└── types/        # TypeScript type definitions

Testing Strategy

Unit tests for utilities and hooks
Integration tests for tRPC procedures
E2E tests for critical user flows
Performance testing for real-time features

Deployment Pipeline

Run tests and type checking
Build Docker image
Run security scans
Deploy to staging
Run smoke tests
Deploy to production

🤝 Contributing Guidelines

For AI Agents

Always reference the documentation before implementing
Follow the patterns established in the Implementation Guide
Ensure all code follows the rules in rules.txt
Implement comprehensive error handling
Add proper TypeScript types for all code

Code Quality Standards

No any types in TypeScript
All components must be accessible (WCAG 2.1 AA)
API routes must have proper validation
Database queries must be optimized
Real-time features must handle disconnections

📞 Support and Resources

Documentation Updates

This documentation is designed to be comprehensive and self-contained. If you identify gaps or need clarification:

Check all related documents first
Look for patterns in the Implementation Guide
Reference the rules.txt for coding standards

Key Integration Points

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

🎯 Success Criteria

The implementation is considered successful when:

All features from Feature Requirements are implemented
All API routes from API Routes document are functional
Database schema matches the specification exactly
Real-time features work reliably
Security requirements are met
Performance targets are achieved

📝 Document Versions

Version: 1.0.0
Last Updated: December 2024
Target Platform: HRIStudio v1.0

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