Phase 3: Implement personalization signals (branch/year onboarding + ranking boost)

Start with PRD §8.8 and inspect src/db/schema.ts, src/app/onboarding/page.tsx, src/app/onboarding/actions.ts, src/lib/resources.ts, src/components/directory/directory-client.tsx, src/proxy.ts, and scripts/normalize-data.ts. Trace the existing authentication, directory sorting, resource tags, and database conventions before choosing among the listed branch-mapping options. Done means optional branch/year onboarding, persisted profiles, incomplete-profile routing, and a non-filtering personalized ranking are covered by the acceptance criteria.

Description

Implement personalization signals as specified in PRD §8.8. This is a P1 requirement for Phase 3.

Acceptance Criteria (from PRD §8.8)

• Onboarding asks branch + year (optional, skippable)
• Resources tagged to a branch (e.g., MATLAB, SolidWorks → ECE/Mechanical) sort higher for matching users — a ranking boost, never a hard filter

Current State

• No user profile table exists yet (only Supabase auth.users)
• Resources have tags but no branch mapping
• No onboarding flow exists
• Directory sorting currently: recommended (Fuse.js relevance), name, recent

Implementation Plan

1. Create profiles table (extends Supabase auth.users):
   • userId (uuid, PK, references auth.users)
   • branch (text, nullable) - e.g., "CSE", "ECE", "Mechanical", "Civil", etc.
   • year (integer, nullable) - 1, 2, 3, 4, 5+
   • completedOnboarding (boolean, default false)
2. Add branch tags to resources:
   • Map existing tags to branches (e.g., "MATLAB" → "ECE", "SolidWorks" → "Mechanical")
   • Could add branchTags column to resources or use existing tags with a mapping
3. Onboarding flow:
   • After first sign-in, redirect to /onboarding if not completed
   • Simple form: branch (select), year (select), skip button
   • Store in profiles table
4. Personalized sorting:
   • New sort option: "For you" (default for logged-in users with profile)
   • Boost resources matching user's branch/year
   • Ranking boost, not hard filter — all resources still visible

Files to Create/Modify

• src/db/schema.ts - add profiles table
• src/app/onboarding/page.tsx (new) - onboarding form
• src/app/onboarding/actions.ts (new) - Server Action to save profile
• src/lib/resources.ts - add getUserProfile(), getPersonalizedResources()
• src/components/directory/directory-client.tsx - add "For you" sort option
• src/proxy.ts - redirect to onboarding if profile incomplete
• scripts/normalize-data.ts - add branch tag mapping (or separate seed)

Database Schema Addition

export const profiles = pgTable('profiles', {
  userId: uuid('user_id').notNull().references(() => auth.users.id).primaryKey(),
  branch: text('branch'), // 'CSE', 'ECE', 'Mechanical', 'Civil', 'EEE', etc.
  year: integer('year'), // 1, 2, 3, 4, 5
  completedOnboarding: boolean('completed_onboarding').notNull().default(false),
  createdAt: timestamp('created_at').notNull().defaultNow(),
  updatedAt: timestamp('updated_at').notNull().defaultNow(),
}).enableRLS();

Branch Mapping Strategy

Option A: Add branchTags array column to resources (explicit mapping)
Option B: Use existing tags with a static mapping in code (e.g., BRANCH_TAG_MAP = { 'MATLAB': 'ECE', ... })
Option C: Add branch column to resources (single branch per resource)

Recommend Option B for simplicity - use existing tags with a mapping config.

Sorting Algorithm

• Base score from Fuse.js (if searching) or 1.0
• If user has branch: +0.5 for each matching branch tag
• If user has year: +0.2 for resources relevant to that year (e.g., internships for year 3-4)
• Sort by combined score descending