hristudio/docs/quick-reference.md

HRIStudio Quick Reference Guide

🚀 Getting Started (5 Minutes)

Prerequisites

• Bun (package manager)
• PostgreSQL 14+
• Docker (optional)

Quick Setup

# Clone and install
git clone <repo-url> hristudio
cd hristudio
bun install

# Start database
bun run docker:up

# Setup database
bun db:push
bun db:seed

# Sync plugin repositories (admin only)
# This populates the plugin store with robot plugins
# from https://repo.hristudio.com

# Start development
bun dev

Default Login

• Admin: sean@soconnor.dev / password123
• Researcher: alice.rodriguez@university.edu / password123
• Wizard: emily.watson@lab.edu / password123

---

📁 Project Structure

src/
├── app/                    # Next.js App Router pages
│   ├── (auth)/            # Authentication pages
│   ├── (dashboard)/       # Main application
│   └── api/               # API routes
├── components/            # UI components
│   ├── ui/                # shadcn/ui components
│   ├── experiments/       # Feature components
│   ├── studies/
│   ├── participants/
│   └── trials/
├── server/               # Backend code
│   ├── api/routers/      # tRPC routers
│   ├── auth/             # NextAuth config
│   └── db/               # Database schema
└── lib/                  # Utilities

---

🎯 Key Concepts

Hierarchical Structure

Study → Experiment → Trial → Step → Action

User Roles

• Administrator: Full system access
• Researcher: Create studies, design experiments
• Wizard: Execute trials, control robots
• Observer: Read-only access

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

---

🛠 Development Commands

Command	Purpose
bun dev	Start development server
bun build	Build for production
bun typecheck	TypeScript validation
bun lint	Code quality checks
bun db:push	Push schema changes
bun db:seed	Seed test data
bun db:studio	Open database GUI

---

🌐 API Reference

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
• robots: Integration, communication, actions, plugins
• admin: Repository management, system settings

Example Usage

// Get user's studies
const studies = api.studies.getUserStudies.useQuery();

// Create new experiment
const createExperiment = api.experiments.create.useMutation();

---

🗄️ Database Quick Reference

Core Tables

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

Key Relationships

studies → experiments → trials
studies → participants
trials → trial_events
experiments → steps

---

🎨 UI Components

Layout Components

// Page wrapper with navigation
<PageLayout title="Studies" description="Manage research studies">
  <StudiesTable />
</PageLayout>

// Entity forms (unified pattern)
<EntityForm 
  mode="create"
  entityName="Study"
  form={form}
  onSubmit={handleSubmit}
/>

// Data tables (consistent across entities)
<DataTable 
  columns={studiesColumns}
  data={studies}
  searchKey="name"
/>

Form Patterns

// Standard form setup
const form = useForm<StudyFormData>({
  resolver: zodResolver(studySchema),
  defaultValues: { /* ... */ }
});

// Unified submission
const onSubmit = async (data: StudyFormData) => {
  await createStudy.mutateAsync(data);
  router.push(`/studies/${result.id}`);
};

---

🔐 Authentication

Protecting Routes

// Middleware protection
export default withAuth(
  function middleware(request) {
    // Route logic
  },
  {
    callbacks: {
      authorized: ({ token }) => !!token,
    },
  }
);

// Component protection
const { data: session, status } = useSession();
if (status === "loading") return <Loading />;
if (!session) return <SignIn />;

Role Checking

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

// Core blocks loaded from hristudio-core repository
await registry.loadCoreBlocks();

// Block categories:
// - 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 (8): observe_behavior, record_audio, etc.

Plugin Repository System

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

interface Plugin {
  id: string;
  name: string;
  version: string;
  trustLevel: 'official' | 'verified' | 'community';
  actionDefinitions: RobotAction[];
  metadata: {
    platform: string;
    category: string;
    repositoryId: string;
  };
}

Repository Integration

• Live Repository: https://repo.hristudio.com
• Core Repository: https://core.hristudio.com
• Auto-sync: Admin dashboard → Repositories → Sync
• Plugin Store: Browse → Install → Use in experiments

---

📊 Common Patterns

Error Handling

try {
  await mutation.mutateAsync(data);
  toast.success("Success!");
  router.push("/success-page");
} catch (error) {
  setError(error.message);
  toast.error("Failed to save");
}

Loading States

const { data, isLoading, error } = api.studies.getAll.useQuery();

if (isLoading) return <Skeleton />;
if (error) return <ErrorMessage error={error} />;
return <DataTable data={data} />;

Form Validation

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

# 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

# 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

---

🔧 Troubleshooting

Common Issues

Build Errors

# Clear cache and rebuild
rm -rf .next
bun run build

Database Issues

# Reset database
bun db:push --force
bun db:seed

TypeScript Errors

# 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

Further Reading

Documentation Files

• Project Overview: Complete feature overview
• Implementation Details: Architecture decisions and patterns
• Database Schema: Complete database documentation
• API Routes: Comprehensive API reference
• Core Blocks System: Repository-based block architecture
• Plugin System Guide: Robot integration guide
• Project Status: Current development status

External Resources

• Next.js Documentation
• tRPC Documentation
• Drizzle ORM Guide
• shadcn/ui Components

---

🎯 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. Sync plugin repositories after setup for full functionality

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

---

This quick reference covers the most commonly needed information for HRIStudio development. For detailed implementation guidance, refer to the comprehensive documentation files.