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-23 19:27:51 -04:00 · 2026-03-22 16:38:28 -04:00
parent add3380307
commit cf3597881b
46 changed files with 439 additions and 1193 deletions
--- a/docs/_archive/route-consolidation-summary.md
+++ b/docs/_archive/route-consolidation-summary.md
@@ -0,0 +1,264 @@
+# Route Consolidation Summary
+
+## Overview
+
+This document summarizes the comprehensive route consolidation work completed in September 2024, which transformed HRIStudio from a fragmented routing structure with duplicated global and study-specific views into a clean, study-scoped architecture.
+
+## Problem Statement
+
+### Issues with Original Architecture
+- **Route Confusion**: Duplicate routes for participants (`/participants` and `/studies/[id]/participants`) and trials (`/trials` and `/studies/[id]/trials`)
+- **Code Duplication**: Separate components for global and study-specific views with 90% overlapping functionality
+- **Navigation Inconsistency**: Users confused about where to find functionality
+- **Maintenance Burden**: Changes required updates to multiple similar components
+- **Dashboard 404**: The `/dashboard` route was incorrectly configured and not accessible
+
+### Technical Debt
+- `participants-data-table.tsx` vs `ParticipantsTable.tsx`
+- `trials-data-table.tsx` vs `TrialsTable.tsx`
+- Inconsistent breadcrumb patterns
+- Broken links in navigation dropdowns
+- Multiple creation flows for the same entities
+
+## Solution: Study-Scoped Architecture
+
+### Design Principles
+1. **Single Source of Truth**: One route and component per entity type
+2. **Logical Hierarchy**: Studies as the primary organizational unit
+3. **Consistent Navigation**: All entity management flows through studies
+4. **User-Friendly Transitions**: Helpful redirects for moved functionality
+
+### Final Route Structure
+
+```
+Global Routes (Platform-Level):
+├── /dashboard                    # Overview across all user's studies
+├── /studies                     # Study management hub
+├── /profile                     # User account management
+└── /admin                       # System administration
+
+Study-Scoped Routes (All Study-Dependent Functionality):
+├── /studies/[id]                # Study details and overview
+├── /studies/[id]/participants   # Participant management for study
+├── /studies/[id]/trials        # Trial management for study
+├── /studies/[id]/experiments    # Experiment protocols for study
+├── /studies/[id]/plugins       # Robot plugins for study
+├── /studies/[id]/analytics     # Analytics for study
+└── /studies/[id]/edit          # Study configuration
+
+Individual Entity Routes (Preserved):
+├── /trials/[trialId]           # Individual trial details
+├── /trials/[trialId]/wizard    # Trial execution interface (TO BE BUILT)
+├── /trials/[trialId]/analysis  # Trial data analysis
+├── /experiments/[id]           # Individual experiment details
+├── /experiments/[id]/edit      # Edit experiment
+└── /experiments/[id]/designer  # Visual experiment designer
+
+Helpful Redirect Routes (User-Friendly Transitions):
+├── /participants               # Redirects to study selection
+├── /trials                     # Redirects to study selection
+├── /experiments                # Redirects to study selection
+├── /plugins                    # Redirects to study selection
+└── /analytics                  # Redirects to study selection
+```
+
+## Implementation Details
+
+### 1. Complete Route Cleanup
+**Converted to Study-Scoped Routes:**
+- `/experiments` → `/studies/[id]/experiments`
+- `/plugins` → `/studies/[id]/plugins`  
+- `/plugins/browse` → `/studies/[id]/plugins/browse`
+
+**Converted to Helpful Redirects:**
+- `/participants` → Shows study selection guidance
+- `/trials` → Shows study selection guidance
+- `/experiments` → Shows study selection guidance  
+- `/plugins` → Shows study selection guidance
+- `/analytics` → Shows study selection guidance (already existed)
+
+**Eliminated Duplicates:**
+- Removed duplicate experiment creation routes
+- Consolidated plugin management to study-scoped only
+- Unified all study-dependent functionality under `/studies/[id]/`
+
+### 2. Dashboard Route Fix
+**Problem**: `/dashboard` was 404ing due to incorrect route group usage
+**Solution**: Moved dashboard from `(dashboard)` route group to explicit `/dashboard` route
+
+**Before:**
+```
+/app/(dashboard)/page.tsx  # Conflicted with /app/page.tsx for root route
+```
+
+**After:**
+```
+/app/dashboard/page.tsx    # Explicit /dashboard route
+/app/dashboard/layout.tsx  # Uses existing (dashboard) layout
+```
+
+### 3. Helpful Redirect Pages
+Created user-friendly redirect pages for moved routes:
+
+**`/participants`** → Shows explanation and redirects to studies
+**`/trials`** → Shows explanation and redirects to studies
+**`/analytics`** → Shows explanation and redirects to studies
+
+**Features:**
+- Auto-redirect if user has selected study in context
+- Clear explanation of new location
+- Maintains dashboard layout with sidebar
+- Action buttons to navigate to studies
+
+### 4. Navigation Updates
+**App Sidebar:**
+- Removed global "Participants" and "Trials" navigation items
+- Kept study-focused navigation structure
+
+**Dashboard Quick Actions:**
+- Updated to focus on study creation and browsing
+- Removed broken links to non-existent routes
+
+**Breadcrumbs:**
+- Updated all entity forms to use study-scoped routes
+- Fixed ParticipantForm and TrialForm navigation
+- Consistent hierarchy: Dashboard → Studies → [Study] → [Entity]
+
+### 5. Form and Component Updates
+**ParticipantForm:**
+- Updated all breadcrumb references to use study-scoped routes
+- Fixed redirect after deletion to go to study participants
+- Updated back/list URLs to be study-scoped
+
+**TrialForm:**
+- Similar updates to ParticipantForm
+- Fixed navigation consistency
+
+**Component Cleanup:**
+- Removed unused imports (Users, TestTube icons)
+- Fixed ESLint errors (apostrophe escaping)
+- Removed duplicate functionality
+
+### 6. Custom 404 Handling
+**Created:** `/app/(dashboard)/not-found.tsx`
+- Uses dashboard layout (sidebar intact)
+- User-friendly error message
+- Navigation options to recover
+- Consistent with platform design
+
+## Benefits Achieved
+
+### 1. Architectural Consistency  
+- **Complete Study-Scoped Architecture**: All study-dependent functionality properly organized
+- **Eliminated Route Confusion**: No more duplicate global/study routes
+- **Clear Mental Model**: Platform-level vs Study-level functionality clearly separated
+- **Unified Navigation Logic**: Single set of breadcrumb patterns
+- **Reduced Maintenance**: Changes only need to be made in one place
+
+### 2. Improved User Experience
+- **Logical Flow**: Studies → Participants/Trials/Analytics makes intuitive sense
+- **Reduced Confusion**: No more "where do I find participants?" questions
+- **Helpful Transitions**: Users with bookmarks get guided to new locations
+- **Consistent Interface**: All entity management follows same patterns
+
+### 3. Better Architecture
+- **Single Responsibility**: Each route has one clear purpose
+- **Hierarchical Organization**: Reflects real-world research workflow
+- **Maintainable Structure**: Clear separation of concerns
+- **Type Safety**: All routes properly typed with no compilation errors
+
+### 4. Enhanced Navigation
+- **Clear Hierarchy**: Dashboard → Studies → Study Details → Entity Management
+- **Breadcrumb Consistency**: All pages follow same navigation pattern
+- **Working Links**: All navigation items point to valid routes
+- **Responsive Design**: Layout works across different screen sizes
+
+## Migration Guide
+
+### For Users
+1. **Bookmarks**: Update any bookmarks from global routes (`/experiments`, `/plugins`, etc.) to study-specific routes
+2. **Workflow**: Access all study-dependent functionality through studies rather than global views
+3. **Navigation**: Use sidebar study-aware navigation - select study context first, then access study-specific functionality
+4. **Redirects**: Helpful guidance pages automatically redirect when study context is available
+
+### For Developers
+1. **Components**: Use study-scoped routes for all study-dependent functionality
+2. **Routing**: All study-dependent entity links should go through `/studies/[id]/` structure
+3. **Forms**: Use study-scoped back/redirect URLs  
+4. **Navigation**: Sidebar automatically shows study-dependent items when study is selected
+5. **Context**: Components automatically receive study context through URL parameters
+
+## Testing Results
+
+### Before Complete Cleanup
+- Route duplication between global and study-scoped functionality
+- Navigation confusion about where to find study-dependent features  
+- Inconsistent sidebar behavior based on study selection
+
+### After Complete Cleanup
+- `/dashboard` → ✅ Global overview with study filtering
+- `/studies` → ✅ Study management hub
+- `/profile` → ✅ User account management
+- `/admin` → ✅ System administration
+- **Study-Scoped Functionality:**
+  - `/studies/[id]/participants` → ✅ Study participants
+  - `/studies/[id]/trials` → ✅ Study trials  
+  - `/studies/[id]/experiments` → ✅ Study experiments
+  - `/studies/[id]/plugins` → ✅ Study plugins
+  - `/studies/[id]/analytics` → ✅ Study analytics
+- **Helpful Redirects:**
+  - `/participants`, `/trials`, `/experiments`, `/plugins`, `/analytics` → ✅ User guidance
+
+### Quality Metrics
+- **TypeScript**: ✅ Zero compilation errors
+- **ESLint**: ✅ All linting issues resolved
+- **Build**: ✅ Successful production builds
+- **Navigation**: ✅ All links functional
+- **Layout**: ✅ Consistent sidebar across all routes
+
+## Lessons Learned
+
+### Route Group Usage
+- Route groups `(name)` are for organization, not URL structure
+- Use explicit routes for specific URLs like `/dashboard`
+- Be careful about root route conflicts
+
+### Component Architecture
+- Prefer single components with conditional logic over duplicates
+- Use consistent naming patterns across similar components
+- Implement proper TypeScript typing for all route parameters
+
+### User Experience
+- Provide helpful redirect pages for moved functionality
+- Maintain layout consistency during navigation changes
+- Clear breadcrumb hierarchies improve user orientation
+
+### Migration Strategy
+- Fix routing issues before making major changes
+- Update all navigation references systematically
+- Test thoroughly after each phase of changes
+
+## Future Considerations
+
+### Potential Enhancements
+1. **Study Context Persistence**: Remember selected study across sessions
+2. **Quick Study Switching**: Add study switcher to global navigation
+3. **Advanced Analytics**: Study comparison tools across multiple studies
+4. **Bulk Operations**: Multi-study management capabilities
+
+### Monitoring
+- Track 404 errors to identify any missed route references
+- Monitor user behavior to ensure new navigation is intuitive
+- Collect feedback on the study-scoped workflow
+
+## Conclusion
+
+The route consolidation successfully transformed HRIStudio from a confusing dual-route system into a clean, study-scoped architecture. This change eliminates significant technical debt, improves user experience, and creates a more maintainable codebase while preserving all functionality.
+
+The implementation demonstrates best practices for large-scale routing refactors in Next.js applications, including helpful user transitions, comprehensive testing, and maintaining backward compatibility through intelligent redirects.
+
+**Status**: Complete ✅  
+**Impact**: Major improvement to platform usability and maintainability  
+**Technical Debt Reduction**: ~60% reduction in duplicate routing/component code  
+**Architectural Consistency**: 100% study-dependent functionality properly scoped  
+**Navigation Clarity**: Clear separation of platform-level vs study-level functionality