mirror of https://github.com/soconnor0919/hristudio.git synced 2026-03-23 19:27:51 -04:00

Files

Sean O'Connor cf3597881b 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

2026-03-22 16:38:28 -04:00

5.8 KiB

Executable File

Raw Blame History

HRIStudio Documentation

HRIStudio is a web-based Wizard-of-Oz platform for Human-Robot Interaction research.

Quick Links

Document	Description
Quick Reference	Essential commands, setup, troubleshooting
Project Status	Current development state (March 2026)
Implementation Guide	Full technical implementation
NAO6 Integration	Robot setup and commands

Getting Started

1. Clone & Install

git clone https://github.com/soconnor0919/hristudio.git
cd hristudio
git submodule update --init --recursive
bun install

2. Start Database

bun run docker:up
bun db:push
bun db:seed

3. Start Application

bun dev
# Visit http://localhost:3000
# Login: sean@soconnor.dev / password123

4. Start NAO6 Robot (optional)

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

Hierarchical Structure: Study → Experiment → Trial → Step → Action
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

System Components

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

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

// 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

# 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

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)

Last Updated: March 22, 2026

5.8 KiB Executable File Raw Blame History