From 3b9c0cc31bef16262846c31e83a3e668835a69ad Mon Sep 17 00:00:00 2001 From: Sean O'Connor Date: Fri, 18 Jul 2025 16:50:35 -0400 Subject: [PATCH] Add development rules and coding standards --- .rules | 150 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 .rules diff --git a/.rules b/.rules new file mode 100644 index 0000000..5e38a33 --- /dev/null +++ b/.rules @@ -0,0 +1,150 @@ +ççYou are an expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Radix UI, Tailwind CSS, tRPC, Drizzle ORM, NextAuth.js v5, and the HRIStudio platform architecture. + +Project Context +- HRIStudio is a web-based platform for managing Wizard of Oz (WoZ) studies in Human-Robot Interaction research +- Uses PostgreSQL for structured data and MinIO (S3-compatible) for media storage +- Implements role-based access control with four primary roles: Administrator, Researcher, Wizard, Observer +- Features a hierarchical experiment structure: Study > Experiment > Step > Action +- Requires real-time communication for wizard control during trials + +Code Style and Structure +- Write concise, technical TypeScript code with accurate examples +- Use functional and declarative programming patterns; avoid classes +- Prefer iteration and modularization over code duplication +- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError, canEdit, shouldFetch) +- Structure files: exported component, subcomponents, helpers, static content, types +- Keep components focused and composable + +Naming Conventions +- Use lowercase with dashes for directories (e.g., components/experiment-designer, features/trial-execution) +- Favor named exports for components and utilities +- Use PascalCase for component files (e.g., ExperimentDesigner.tsx, WizardInterface.tsx) +- Use camelCase for utility files (e.g., robotPlugin.ts, trialValidation.ts) +- Prefix database schema files with 'schema.' (e.g., schema.studies.ts, schema.experiments.ts) + +TypeScript Usage +- Use TypeScript for all code; prefer interfaces over types for component props +- Define explicit return types for all functions +- Use const assertions for literal types +- Avoid enums; use const objects with 'as const' instead +- Create shared types in dedicated type files (e.g., types/experiment.ts, types/trial.ts) +- Use Zod schemas for runtime validation, infer TypeScript types from Zod + +File Organization +src/ +├── app/ # Next.js app router +│ ├── (auth)/ # Auth-related pages +│ ├── (dashboard)/ # Authenticated app pages +│ ├── api/ # API routes +│ └── layout.tsx +├── components/ # Shared UI components +│ ├── ui/ # Shadcn UI components +│ ├── experiment/ # Experiment-related components +│ ├── trial/ # Trial execution components +│ └── layout/ # Layout components +├── features/ # Feature-specific modules +│ ├── auth/ # Authentication logic +│ ├── experiments/ # Experiment design +│ ├── trials/ # Trial execution +│ └── analysis/ # Data analysis +├── lib/ # Utilities and configurations +│ ├── db/ # Database setup and schemas +│ ├── trpc/ # tRPC setup and routers +│ ├── auth/ # NextAuth configuration +│ └── plugins/ # Robot plugin system +├── hooks/ # Custom React hooks +└── types/ # Shared TypeScript types + +Database Patterns (Drizzle) +- Define schemas using Drizzle's PostgreSQL dialect +- Use UUID primary keys with gen_random_uuid() +- Implement soft deletes with deleted_at timestamps +- Add created_at and updated_at to all tables +- Use JSONB for flexible metadata storage +- Create database indexes for foreign keys and frequently queried fields +- Use transactions for multi-table operations + +tRPC Patterns +- Organize routers by domain (auth, studies, experiments, trials, etc.) +- Use input validation with Zod schemas +- Implement middleware for authentication and authorization +- Return consistent error responses with proper error codes +- Use optimistic updates on the client for better UX +- Implement proper TypeScript inference throughout + +Authentication & Authorization +- Use NextAuth.js v5 with database sessions +- Implement role-based middleware in tRPC +- Check permissions at both route and resource level +- Store user roles in database with proper relationships +- Use React context for client-side auth state +- Implement audit logging for sensitive operations + +Component Patterns +- Create compound components for complex UI (e.g., ExperimentDesigner.Canvas, ExperimentDesigner.Toolbar) +- Use Radix UI primitives wrapped with Shadcn UI styling +- Implement proper loading and error states +- Use Suspense boundaries for async components +- Create reusable form components with react-hook-form +- Implement keyboard navigation for accessibility + +Real-time Features +- Use WebSockets for trial execution updates +- Implement reconnection logic for connection failures +- Use event-based patterns for real-time communication +- Maintain synchronization between server and client state +- Buffer events during disconnections + +State Management +- Use URL state (nuqs) for shareable application state +- Leverage React Server Components for initial data fetching +- Use tRPC's useQuery with proper cache strategies +- Implement optimistic updates for user actions +- Keep client state minimal; prefer server state + +Performance Optimization +- Minimize 'use client' directives; favor RSC +- Implement virtual scrolling for large lists +- Use dynamic imports for heavy components +- Optimize images with Next.js Image component +- Implement proper database query optimization +- Use React.memo sparingly and only when measured + +Security Best Practices +- Validate all inputs on both client and server +- Implement rate limiting on sensitive endpoints +- Use parameterized queries (handled by Drizzle) +- Encrypt sensitive data in database +- Implement CSRF protection +- Use secure HTTP headers via Next.js config + +Testing Approach +- Write integration tests for tRPC procedures +- Test authorization logic thoroughly +- Use MSW for mocking external services +- Test critical user flows with Playwright +- Ensure proper error handling in tests + +Specific HRIStudio Patterns +- Robot plugins must implement the standard interface +- Trial execution follows strict state machine patterns +- Maintain audit trail for all experiment modifications +- Use event sourcing for trial execution history +- Implement version control for experiment designs +- Support offline-capable wizard interfaces + +Error Handling +- Use custom error classes for different error types +- Implement global error boundary for React +- Log errors with appropriate context +- Show user-friendly error messages +- Implement retry logic for transient failures + +Accessibility +- Follow WCAG 2.1 AA standards +- Implement proper ARIA labels +- Ensure keyboard navigation throughout +- Test with screen readers +- Provide visual feedback for all actions + +Follow Next.js 14 best practices for Data Fetching, Rendering, and Routing.