feat: Add smart package recommendations feature

- Implement onboarding modal with 3-step wizard - Category selection (up to 3 categories) - OS detection with manual override - Experience level selection - Add intelligent recommendation engine - Hybrid scoring algorithm (category 40%, popularity 30%, OS 20%, preset 10%) - 7 curated categories with preset packages - Support for all platforms (Windows, macOS, Ubuntu, Debian, Arch, Fedora) - Create recommendation UI components - RecommendationsSection with grid layout - Package cards with recommendation scores and reasons - User profile display with customization options - Add localStorage-based profile management - Persistent user preferences - Automatic OS detection - Profile CRUD operations via useRecommendationProfile hook - Implement API endpoint - POST /api/recommendations - GET /api/recommendations (query params) - Request validation and error handling - Add full i18n support - English and Turkish translations - Onboarding flow, categories, and UI labels - Update TypeScript config (lib: es2017 for array.includes) Closes #1
2026-09-11 10:36:07 +00:00 · 2025-11-22 16:20:36 +03:00
parent afd4456893
commit 73f9248e98
12 changed files with 2169 additions and 8 deletions
@@ -0,0 +1,261 @@
+# Smart Package Recommendations Feature
+
+## 📋 Overview
+
+This feature adds intelligent package recommendations to RepoHub based on user preferences, operating system, and experience level. It provides a personalized onboarding experience and curated package suggestions.
+
+## ✨ Key Features
+
+### 1. **Onboarding Modal**
+- 3-step wizard for new users
+- Category selection (up to 3 categories)
+- OS detection with manual override option
+- Experience level selection (beginner/intermediate/advanced)
+- Persistent localStorage-based profile
+
+### 2. **Smart Recommendations**
+- Hybrid scoring algorithm:
+  - Category match: 40%
+  - Popularity: 30%
+  - OS compatibility: 20%
+  - Preset boost: 10%
+- Curated preset packages for 7 categories
+- Real-time filtering based on user profile
+
+### 3. **Categories Supported**
+- 💻 **Development**: IDEs, version control, programming languages
+- 🎨 **Design**: Graphics editors, 3D tools, UI/UX software
+- 🎬 **Multimedia**: Video/audio editing, media players
+- ⚙️ **System Tools**: Admin tools, utilities, monitoring
+- 🎮 **Gaming**: Game platforms, communication tools
+- 📝 **Productivity**: Office suites, note-taking, password managers
+- 🎓 **Education**: Learning tools, scientific software
+
+## 🏗️ Architecture
+
+### Components
+
+```
+src/
+├── types/
+│   └── recommendations.ts          # Type definitions
+├── data/
+│   └── recommendationPresets.ts    # Hardcoded package presets
+├── services/
+│   └── recommendationService.ts    # Recommendation algorithm
+├── hooks/
+│   └── useRecommendationProfile.ts # localStorage management + OS detection
+├── components/
+│   ├── OnboardingModal.tsx         # User onboarding wizard
+│   └── RecommendationsSection.tsx  # Recommendation display
+└── app/api/
+    └── recommendations/
+        └── route.ts                # API endpoint
+```
+
+### Data Flow
+
+```
+1. First Visit
+   └→ useRecommendationProfile detects !hasCompletedOnboarding
+   └→ OnboardingModal opens automatically
+   └→ User selects categories, OS, experience level
+   └→ Profile saved to localStorage
+   └→ hasCompletedOnboarding = true
+
+2. Recommendations
+   └→ RecommendationsSection fetches from /api/recommendations
+   └→ POST { platform_id, categories, experienceLevel }
+   └→ RecommendationService.generateRecommendations()
+   └→ Fetch preset packages (exact name match)
+   └→ Fetch category packages (popularity-based)
+   └→ Score each package (hybrid algorithm)
+   └→ Return top 12 recommendations
+
+3. User Actions
+   └→ Click "Customize Preferences" → Reopen OnboardingModal
+   └→ Click "Refresh Recommendations" → Refetch recommendations
+   └→ Click package card → Add to selection
+```
+
+## 🔧 API Usage
+
+### POST /api/recommendations
+
+**Request:**
+```json
+{
+  "platform_id": "ubuntu",
+  "categories": ["development", "productivity"],
+  "experienceLevel": "intermediate",
+  "limit": 12
+}
+```
+
+**Response:**
+```json
+{
+  "recommendations": [
+    {
+      "id": "pkg-uuid",
+      "name": "git",
+      "description": "Version control system",
+      "version": "2.43.0",
+      "recommendationScore": 95,
+      "recommendationReason": "Version control system essential for all developers",
+      "presetMatch": true,
+      ...
+    }
+  ],
+  "total": 12,
+  "userProfile": {
+    "categories": ["development", "productivity"],
+    "platform": "ubuntu",
+    "experienceLevel": "intermediate"
+  }
+}
+```
+
+### GET /api/recommendations
+
+Query parameters version (alternative to POST):
+```
+GET /api/recommendations?platform_id=ubuntu&categories=development,productivity&experience_level=intermediate&limit=12
+```
+
+## 🎨 UI/UX Features
+
+### Onboarding Modal
+- **Step 1**: Category selection with icons and descriptions
+- **Step 2**: OS selection (auto-detected + manual override)
+- **Step 3**: Experience level with detailed descriptions
+- Progress indicator (3 dots)
+- Back/Next navigation
+- Validation (can't proceed without required selections)
+
+### Recommendations Section
+- Grid layout (responsive: 1/2/3 columns)
+- Package cards with:
+  - "Essential" badge for preset matches
+  - Recommendation score (0-100%) with progress bar
+  - Recommendation reason
+  - Version info
+  - Add to selection button
+- User profile pills (OS + categories)
+- Refresh button
+- Customize preferences button
+
+## 🌍 i18n Support
+
+Full English and Turkish translations for:
+- Onboarding flow
+- Category names and descriptions
+- Experience levels
+- Recommendation UI labels
+- Button text
+
+Translation keys:
+- `onboarding.*`
+- `categories.*`
+- `recommendations.*`
+
+## 💾 localStorage Schema
+
+```typescript
+// Key: 'repohub_user_profile'
+{
+  categories: ['development', 'productivity'],
+  detectedOS: 'ubuntu',
+  selectedOS?: 'arch',              // Manual override
+  experienceLevel: 'intermediate',
+  hasCompletedOnboarding: true,
+  createdAt: '2025-11-22T10:00:00Z',
+  lastUpdated: '2025-11-22T12:30:00Z'
+}
+```
+
+## 🧪 Testing Checklist
+
+- [ ] First visit triggers onboarding modal
+- [ ] OS detection works correctly (Windows/macOS/Linux)
+- [ ] Category selection validates (max 3)
+- [ ] Profile persists across page reloads
+- [ ] Recommendations update when profile changes
+- [ ] Package cards are clickable and add to selection
+- [ ] "Customize Preferences" reopens onboarding
+- [ ] "Refresh Recommendations" fetches new data
+- [ ] i18n works (EN/TR switching)
+- [ ] Responsive design on mobile/tablet/desktop
+- [ ] Loading states display correctly
+- [ ] Error states handle gracefully
+
+## 🔮 Future Enhancements
+
+### Phase 2 (Post-MVP)
+- [ ] Database storage for user profiles (optional account system)
+- [ ] Community ratings for packages
+- [ ] User feedback loop (like/dislike recommendations)
+- [ ] A/B testing for algorithm weights
+- [ ] Admin panel for managing presets
+
+### Phase 3 (ML-Ready)
+- [ ] Collaborative filtering
+- [ ] Package co-occurrence analysis
+- [ ] Time-based trending packages
+- [ ] Machine learning model integration
+
+## 📊 Scoring Algorithm Details
+
+### Hybrid Scoring Formula
+```typescript
+score = 
+  (category_match * 0.4) +
+  (popularity_score / 100 * 0.3) +
+  (os_compatibility * 0.2) +
+  (preset_priority / 10 * 0.1)
+```
+
+### Category Match
+- Preset package: 1.0 (perfect match)
+- Non-preset package: 0.5 (generic match)
+
+### Popularity Score
+- Normalized from 0-100 (from database)
+- Higher popularity = better recommendation
+
+### OS Compatibility
+- All packages from DB are compatible = 1.0
+- Future: could penalize packages with known issues
+
+### Preset Priority
+- Range: 1-10 (defined in presets)
+- Normalized to 0.1-1.0
+- Only applies to preset packages
+
+## 🚀 Deployment Notes
+
+1. No database migrations required (uses existing schema)
+2. No environment variables needed (feature is client-side first)
+3. Compatible with existing API structure
+4. Progressive enhancement (works without JS for basic browse)
+
+## 📝 Code Quality
+
+- ✅ TypeScript strict mode
+- ✅ Full type coverage
+- ✅ ESLint compliant
+- ✅ Responsive design
+- ✅ Accessibility (keyboard navigation)
+- ✅ Error boundaries
+- ✅ Loading states
+
+## 🔗 Related Files
+
+- Issue: https://github.com/yusufipk/RepoHub/issues/1
+- Branch: `feature/smart-package-recommendations`
+
+---
+
+**Developed by:** @ersaayan  
+**Date:** November 22, 2025  
+**Status:** ✅ Ready for Review