feat: implement dual-user platform with candidate portal

[jediahjireh]

overview

• transform profileprep into a comprehensive dual-platform serving both recruiters and candidates with parallel organizational structures,
• ai-powered cv analysis, and secure role-based access control.

business impact

• market expansion: extend from recruiters-only to dual b2b segments (recruiting companies + universities/career centers)
• network effects: candidate cv improvements directly benefit recruiter efficiency and placement success
• scalable organizations: universities can manage hundreds of students, recruiting firms can optimize entire talent pipelines
• competitive differentiation: first platform to serve both sides of the talent optimization equation

key features added

candidate portal (/portal/*)

• cv analysis engine: 7-dimensional ai scoring (ats, tone, content, structure, skills, grammar, keywords)
• job-targeted feedback: analyze cv against specific job descriptions for relevance scoring
• progress tracking: historical analysis comparison and improvement trends over time
• organization management: admin candidates can manage members and view aggregate analytics

dual user type system

• parallel authentication: recruiters and candidates maintain separate sessions and data access
• company types: recruiter (agencies) vs candidate_org (universities, career centers)
• role hierarchy: user/admin/superadmin permissions within each user type
• complete data isolation: company-scoped queries prevent cross-organization access

role switching (development only)

• seamless testing: switch between recruiter and candidate modes during development
• security-first: completely disabled in production, only available for isTestAccount: true
• session management: proper logout/login flow maintains data security during switches

enhanced ai integration

• google gemini 2.0: multi-dimensional cv analysis with structured feedback generation
• scoring system: 0-100 scoring across multiple categories with actionable improvement tips
• analysis storage: structured database storage of feedback and historical progress

technical implementation

database architecture

// new cv analysis model for candidates
model CVAnalysis {
  id                String   @id @default(cuid())
  userId            String
  fileName          String
  fileContent       String   @db.Text
  jobTitle          String
  jobDescription    String   @db.Text
  // 7-dimensional scoring system
  overallScore      Int
  atsScore          Int
  toneScore         Int
  contentScore      Int
  structureScore    Int
  skillsScore       Int
  grammarScore      Int
  keywordScore      Int
  // structured feedback storage
  atsFeedback       Json
  toneFeedback      Json
  // ... additional feedback fields
}

// enhanced company model with dual types
model Company {
  companyType         CompanyType     @default(RECRUITER) // RECRUITER | CANDIDATE_ORG
  allowedDocsPerUsers Int             @default(5)
}

// enhanced user model with dual types
model User {
  role          UserRole  @default(USER)      // USER | ADMIN | SUPERADMIN
  userType      UserType  @default(RECRUITER) // RECRUITER | CANDIDATE | TESTER
  isTestAccount Boolean   @default(false)     // enables role switching in dev
}

api endpoints

• POST /api/cv/analyze: process cv analysis with job description context
• POST /api/user/switch-role: handle role switching for test accounts (dev only)
• POST /api/user/update-type: manage user type changes with proper authorization

component architecture

• server components: data fetching with proper authentication and company scoping
• client components: interactive features using tanstack query for real-time updates
• shared components: reusable ui elements across both user types (loading, errors, stats cards)
• role-based rendering: conditional ui based on user type and permissions

security measures

• company-scoped queries: all database operations filtered by companyId and userType
• role-based access: page-level authentication with requireAuth() utility
• demo account isolation: test accounts clearly marked and restricted to development
• session management: proper authentication flows with nextauth v5

pages added/modified

new candidate pages

• /portal - candidate dashboard with personal and organization analytics
• /portal/documents - cv document management and analysis history
• /portal/analyses - detailed cv analysis results and scoring breakdowns
• /portal/progress - career development tracking and improvement metrics
• /portal/settings - profile management and organization membership
• /portal/organization/members - admin: manage organization members (universities, etc.)
• /portal/organization/analytics - admin: organization-wide performance metrics
• /portal/organization/analyses - admin: view all member cv analyses

enhanced recruiter pages

• /recruiter - recruiter dashboard with usage stats and company info
• /recruiter/documents - enhanced document management with real-time queries
• /recruiter/settings - profile management with admin features for company management
• /dashboard/* - admin features with company user management and analytics

shared enhancements

• /app - dual-mode cv processing (generation for recruiters, analysis for candidates)
• /login - enhanced authentication with demo account access and role switching ui

testing & development

demo account system

• recruiter accounts: demo@profileprep.com, admin.demo@profileprep.com
• candidate accounts: candidate.demo@profileprep.com, admin.candidate.demo@profileprep.com
• role switching: seamless switching between user types during development
• data seeding: comprehensive demo data for both user types and companies

development workflow

• role-based testing: verify permissions and access control across all user types
• cross-organization isolation: ensure companies cannot access each other's data
• analytics accuracy: validate dashboard metrics and reporting functionality
• ai integration: test cv analysis with sample documents and job descriptions

reviewer checklist

functionality verification

• candidate portal loads and displays correct analytics for demo candidate accounts
• cv analysis api processes test documents and returns structured feedback
• role switching works in development and is disabled in production
• recruiter features remain fully functional with enhanced ui/ux
• admin features work correctly for both user types (company vs organization management)
• document limits and usage tracking function properly across user types

security validation

• demo accounts only accessible in development mode (node_env=development)
• company-scoped queries prevent cross-organization data access
• role-based page access correctly restricts unauthorized users
• session management maintains proper isolation between user types
• sensitive demo account credentials not exposed in production builds

data integrity

• database migrations apply cleanly without data loss
• seed data creates realistic test scenarios for both user types
• analytics calculations match expected values across dashboards
• cv analysis storage preserves feedback structure and scoring

user experience

• navigation flows logically between different user type interfaces
• error handling provides clear feedback for invalid operations
• loading states display appropriately during ai processing
• responsive design works across device sizes for new portal pages

technical implementation

• typescript types properly defined for new models and api responses
• server actions follow established patterns with proper error handling
• client queries use tanstack query for optimal caching and updates
• component architecture maintains clear separation between server/client logic

documentation

• readme provides comprehensive onboarding guide for new developers
• api documentation covers all new endpoints with request/response examples
• database schema changes documented with migration rationale
• demo account usage instructions clear and security warnings prominent

deployment considerations

• environment variables: ensure google ai api key configured for cv analysis
• database migrations: run npm run db:migrate-pr in production
• demo account security: verify demo accounts disabled in production environment
• performance monitoring: monitor ai api usage and response times
• error tracking: implement logging for cv analysis failures and user role issues

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
profile-prep	Ready	Preview	Comment	Sep 11, 2025 2:23pm

[jediahjireh]

feat: implement comprehensive guidance system with personalised content and progress tracking

overview

• include personalised guidance for both recruiters and candidates from dashboard
• implement sophisticated onboarding flow, with preference collection and dynamic content generation
• add comprehensive progress tracking, analytics and personalised recommendations system

business impact

• enhanced user engagement: personalised guidance tailored to career stage, field and individual preferences
• improved user retention: progress tracking and analytics encourage continued platform usage
• scalable content delivery: dynamic content generation reduces manual content maintenance
• data-driven insights: analytics provide valuable user behaviour data for product improvements
• competitive differentiation: first platform to offer truly personalised, preference-based career guidance

key features added

enhanced onboarding system

• guidance preferences collection: 16-parameter system capturing experience level, goals, challenges and learning style
• dynamic content personalisation: real-time content generation based on user field, specialisation, career stage and preferences
• smart recommendation engine: rule-based topic suggestions using user profile, preferences, completion history and prerequisite logic
• multi-step onboarding flow: streamlined process collecting essential data for content personalisation

comprehensive guidance system

• progress tracking: detailed tracking of topic completion, time spent, and section-by-section progress
• analytics dashboard: personal analytics showing streak days, completion rates, and preferred topics
• bookmark system: save favourite topics for quick access and reference
• personalised recommendations: dynamic suggestions based on prerequisites, completion history and preferences

dual-user content architecture

• candidate guidance topics: cv optimisation, interview prep, career growth, salary negotiation, cover letters
• recruiter guidance topics: sourcing strategies, candidate screening, market insights, job descriptions
• content versioning: different content versions based on field (technology, healthcare, finance) and career stage
• british english localisation: professional, localised content throughout the platform - TODO

advanced content management

• dynamic content generation: real-time philosophy and strategy generation based on user preferences
• time estimation: accurate time estimates for each topic and section
• difficulty levels: beginner, intermediate and advanced content tracks
• prerequisites system: logical learning paths with topic dependencies

technical implementation

database architecture

// comprehensive progress tracking
model GuidanceProgress {
  id                String   @id @default(cuid())
  userId            String
  topicId           String
  userType          UserType
  progress          Int      @default(0) // 0-100
  completed         Boolean  @default(false)
  sectionsCompleted Json     @default("[]")
  timeSpent         Int      @default(0)
  bookmarked        Boolean  @default(false)
  @@unique([userId, topicId, userType])
}

// user analytics and engagement tracking
model GuidanceAnalytics {
  userId               String
  totalTopicsStarted   Int     @default(0)
  totalTopicsCompleted Int     @default(0)
  totalTimeSpent       Int     @default(0)
  averageProgress      Float   @default(0)
  streakDays           Int     @default(0)
  preferredTopics      Json    @default("[]")
}

// enhanced user model with guidance preferences
model User {
  guidancePreferences Json? 
  lastGuidanceAccess  DateTime?
  GuidanceProgress    GuidanceProgress[]
  GuidanceAnalytics   GuidanceAnalytics?
}

api endpoints

• POST /api/user/guidance/preferences — save and update user guidance preferences
• GET /api/user/guidance/access — retrieve user's guidance progress and analytics
• PUT /api/user/onboarding — enhanced onboarding with preferences collection

component architecture

• guidance content system

  • lib/guidance/content/ — generates personalised content
  • lib/guidance/progress-service.ts — handles progress tracking and analytics
  • lib/guidance/content/types.ts — typescript definitions for guidance system

• redesigned guidance hubs

  • /portal/guidance — candidate hub with personalised dashboard
  • /recruiter/guidance — recruiter hub with industry-specific content
  • /guidance/[topic] — individual topic pages with progress tracking

• enhanced ui components

  • components/settings/GuidancePreferences.tsx — settings for preferences
  • components/ui/ — radio groups, sliders for preference collection
  • progress indicators for guidance topics

content structure

comprehensive topic coverage

• candidate topics: cv optimisation, interview preparation, cover letters, career growth, salary negotiation
• recruiter topics: sourcing strategies, candidate screening, market insights, job descriptions, diversity hiring
• cross-cutting: networking, linkedin optimisation, market trends, industry insights

personalisation parameters

• experience levels: entry, mid-level, senior, executive, career changing
• goals: career change, promotion, skill development, job search optimisation
• learning preferences: visual, reading, interactive, video, mixed
• time commitment: flexible scheduling
• industry focus: technology, healthcare, finance with variations

pages added/modified

• /app/onboarding/_components/GuidancePreferencesStep.tsx — onboarding preferences step

• /portal/guidance/[topic]/ — candidate topic pages

• /recruiter/guidance/[topic]/ — recruiter topic pages

• /portal/guidance/_components/GuidanceHub.tsx — candidate hub

• /recruiter/guidance/_components/RecruiterGuidanceHub.tsx — recruiter hub

• /portal/settings and /recruiter/settings — updated settings with guidance preferences

• components/settings/GuidancePreferences.tsx — reusable component

• constants/guidance/*.json — topic definitions

• data/guidance/enhanced-candidate-guidance.json — candidate content

• lib/utils/career-stage.ts — utilities

testing & development

• content validation: preference-based generation, progress tracking, recommendation engine
• data integrity: migration testing, analytics accuracy, preference persistence

reviewer checklist

functionality verification

• onboarding flow collects all 16 parameters
• personalised content generation works per profile
• progress tracking records correctly
• analytics dashboard displays correctly
• bookmarks and recommendations function properly

content quality

• british english localisation consistent - TODO
• difficulty levels correct per topic
• industry-specific variations accurate
• prerequisites logical

user experience

• onboarding intuitive
• hubs show recommendations and progress
• topic pages engaging
• settings allow modification post-onboarding

technical implementation

• database models indexed correctly
• server actions error-handled
• progress tracking efficient
• content generation consistent

data management

• preferences serialise/deserialise correctly
• analytics handle edge cases
• progress tracking resilient
• content versioning future-proof

deployment considerations

• validate content loading in production
• monitor content generation performance
• ensure analytics updates don’t affect ux

---