hristudio/docs/project-status.md

HRIStudio Project Status

Current Status: Active Development

Project Version: 1.0.0
Last Updated: March 2026
Overall Completion: 98%
Status: Thesis research phase

---

Executive Summary

HRIStudio is a complete platform for Wizard-of-Oz HRI research. Key milestones achieved:

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

---

Architecture

Three-Layer Architecture

┌─────────────────────────────────────────────────────┐
│  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)      │
└─────────────────────────────────────────────────────┘

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)

---

Branching Flow

Experiment steps support conditional branching with wizard choices:

Step 3 (Comprehension Check)
  └── wizard_wait_for_response
      ├── Click "Correct" → setLastResponse("Correct") → nextStepId=step4a
      └── Click "Incorrect" → setLastResponse("Incorrect") → nextStepId=step4b

Step 4a/4b (Branches)
  └── conditions.nextStepId: step5.id → convergence point

Step 5 (Story Continues)
  └── Linear progression to Step 6

---

NAO6 Robot Actions (14 total)

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

---

Tech Stack

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

---

Development Status

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

Known Issues

Issue	Status	Notes
robots.executeSystemAction	Known error	Fallback works

---

SSH Deployment Commands

# Local development
bun dev

# Database
bun db:push          # Push schema changes
bun db:seed          # Seed with test data
bun run docker:up   # Start PostgreSQL

# Quality
bun typecheck       # TypeScript validation
bun lint            # ESLint

---

Thesis Timeline

Current phase: March 2026 - Implementation complete, preparing user study

Phase	Status	Date
Proposal	✅	Sept 2025
IRB Application	✅	Dec 2025
Implementation	✅	Feb 2026
User Study	🔄 In Progress	Mar-Apr 2026
Defense	Scheduled	April 2026

---

Next Steps

1. Complete user study (10-12 participants)
2. Data analysis and thesis writing
3. Final defense April 2026
4. Open source release

---

Last Updated: March 22, 2026