🚀 HireMeLah! - Your Career Cockpit

A comprehensive job seeker platform that combines AI-powered resume parsing, intelligent job matching, application tracking, and personalized learning roadmaps to help you land your dream job.

---

📋 Table of Contents

• Overview
• Features
• Tech Stack
• Getting Started
• Project Structure
• Key Algorithms
• Environment Variables
• Usage
• Development
• Documentation

---

🎯 Overview

HireMeLah! is a privacy-first job seeker platform designed specifically for fresh graduates in Singapore. The platform helps users:

• Discover personalized job opportunities using intelligent matching
• Track application status with automated email detection
• Learn with AI-generated roadmaps to bridge skill gaps
• Manage their entire job search journey in one place

Key Philosophy

• Privacy-First: All data stored in browser localStorage, no backend database
• Client-Side Processing: Job matching happens in the browser
• AI-Powered: OpenAI GPT-4o-mini for resume parsing and roadmap generation
• User-Centric: Designed for fresh graduates with entry-level focus

---

✨ Features

1. 🤖 AI-Powered Onboarding

• Resume Parsing: Upload DOCX, PDF, or TXT files

  • Extracts: Education, Experience, Projects, Awards, Skills
  • Assigns proficiency scores (1-10) to each skill automatically
  • Identifies skill categories from 200+ skills database

• Transcript Parsing: Upload academic transcripts

  • Extracts modules/courses with grades
  • Identifies skills learned from each module
  • Tracks academic progress

• Manual Review: Users can review and edit all extracted data before saving

2. 🎯 Intelligent Job Matching

• Career Fit Index (CFI): Composite matching score

  • Skill Fit Index (50%): Compares user skills vs job requirements
  • Relevance Index (50%): Measures alignment with target role
    • Category Match (50% of relevance)
    • Exact Role Match (25% of relevance)
    • Target Role Skills Match (25% of relevance)

• Dynamic Weighting: Users can adjust Skill Fit vs Relevance weights

• Skill Proficiency Matching: Compares user skill scores (1-10) with job requirements

• Multi-Source Job Data: Aggregates jobs from 7 platforms:

  • MyCareersFuture
  • Indeed
  • Glassdoor
  • JobStreet
  • Prosple
  • eFinancialCareers
  • Master Jobs (consolidated)

3. 🔍 Job Discovery & Filtering

• Advanced Filters:

  • Search by keywords
  • Date posted (Today, Past Week, Past Month, Any time)
  • Work arrangement (Remote, Hybrid, On-site)
  • Industry
  • Salary range
  • Employment type (Full-time, Part-time, Contract, Internship)

• Sorting Options:

  • Career Fit Index (default)
  • Skill Fit Index
  • Relevance Index
  • Salary (High to Low, Low to High)
  • Date Posted (Newest, Oldest)

• Job Detail View:

  • Complete job description
  • Skills breakdown with match percentages
  • CFI breakdown (Overall, Skill Fit, Relevance)
  • Company information
  • Direct link to original listing

4. 📊 Application Tracker

• Kanban Board: Visual tracking with columns:

  • Saved / Interested
  • Applied
  • Online Assessment (OA)
  • Interview
  • Offer
  • Rejected
  • Declined
  • No Update (30+ days)

• Drag & Drop: Move applications between statuses

• Application Cards: Display key information:

  • Job title and company
  • Applied date
  • Interview details (date, time, location, type, interviewer)
  • OA details (deadline, platform, duration, deliverable)
  • Offer details (deadline, salary, start date)

• Lifetime Statistics:

  • Total Applied (lifetime)
  • Total Offers (lifetime)
  • Response rate

• Status Change History: Track all status transitions with timestamps

5. 📧 Gmail Integration

• Email Detection: Automatically detects job-related emails

• Status Updates: Identifies:

  • Interview invitations
  • Online assessment deadlines
  • Offer letters
  • Rejection notices

• Smart Matching: Matches emails to applications using:

  • Company name
  • Job title keywords
  • Sender information

• Auto-Extraction: Extracts from email content:

  • Interview date, time, location, type
  • OA deadline, platform, duration, deliverable
  • Offer deadline, salary, start date

6. 📅 Calendar Integration

• Manual Calendar Export: Per-application calendar button

  • Add to Google Calendar
  • Add to Outlook Calendar
  • Download .ics file

• Event Types:

  • Interview events (with location, time, interviewer)
  • OA deadline events
  • Offer deadline events

7. 🗺️ Learning Roadmaps

• AI-Generated Roadmaps: Personalized learning paths to bridge skill gaps

• Target Role Selection: Choose from 100+ roles across 10 categories:

  • Software Engineering
  • Data Science & Analytics
  • Product Design
  • DevOps & Cloud
  • Security
  • Mobile Development
  • Finance & Tech
  • Business Consulting
  • Marketing & Growth
  • Management

• Customizable Constraints:

  • Budget (SGD)
  • Time frame (weeks)
  • Hours per week
  • Preference for free resources
  • Include projects

• Roadmap Structure:

  • Monthly breakdown
  • Weekly tasks
  • Skill-focused learning
  • Project recommendations
  • Resource links

• Progress Tracking: Mark tasks as complete, track budget usage

• Visual Timeline: Bubble timeline view showing progress

8. 👤 Profile Management

• Comprehensive Profile: Edit all aspects of your profile

  • Personal information
  • Education history
  • Work experience
  • Projects
  • Awards & certifications
  • Skills with proficiency scores
  • Academic modules
  • Job preferences (location, salary, work type)
  • Target roles

• Skill Management:

  • Add/remove skills
  • Adjust proficiency scores (1-10)
  • Auto-suggestions from skills database
  • Skills sorted by proficiency (highest to lowest)

---

🛠️ Tech Stack

Frontend

• Next.js 14 - React framework with App Router
• React 18 - UI library with hooks
• TypeScript 5 - Type-safe development
• Tailwind CSS 3 - Utility-first CSS framework
• Lucide React - Icon library

Backend & APIs

• Next.js API Routes - Serverless backend functions
• NextAuth.js 4 - Authentication with Google OAuth
• OpenAI GPT-4o-mini - AI-powered resume and transcript parsing

Data Processing

• CSV Parsing - Job data from multiple sources
• PDF/DOCX Parsing - Document text extraction
• Local Storage - Client-side data persistence

Development Tools

• ESLint - Code linting
• PostCSS & Autoprefixer - CSS processing
• Date-fns - Date manipulation utilities

---

🚀 Getting Started

Prerequisites

• Node.js 18+ and npm
• OpenAI API key (for AI features)
• Google OAuth credentials (optional, for Gmail integration)

Installation

1. Clone the repository

   git clone <repository-url>
   cd jobseeker

2. Install dependencies

   npm install

3. Set up environment variables

   Create a .env.local file in the root directory:

   # OpenAI API Key (Required for AI features)
   OPENAI_API_KEY=your-openai-api-key-here
   
   # NextAuth Configuration (Optional, for Google OAuth)
   NEXTAUTH_URL=http://localhost:3000
   NEXTAUTH_SECRET=your-secret-key-here
   
   # Google OAuth (Optional, for Gmail integration)
   GOOGLE_CLIENT_ID=your-google-client-id
   GOOGLE_CLIENT_SECRET=your-google-client-secret

4. Run the development server

   npm run dev

5. Open your browser

   Navigate to http://localhost:3000

---

📁 Project Structure

jobseeker/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── api/               # API routes (backend)
│   │   │   ├── auth/          # NextAuth authentication
│   │   │   ├── parse-resume/  # AI resume parsing
│   │   │   └── generate-roadmap/ # AI roadmap generation
│   │   ├── jobs/              # Job listing pages
│   │   ├── onboarding/        # First-time user setup
│   │   ├── profile/           # User profile management
│   │   ├── roadmap/          # Learning roadmap view
│   │   └── tracker/           # Application tracker
│   │
│   ├── components/            # React components
│   │   ├── ApplicationTracker.tsx  # Kanban board
│   │   ├── JobCard.tsx        # Job display card
│   │   ├── FilterPanel.tsx   # Job filters
│   │   └── Sidebar.tsx        # Navigation
│   │
│   ├── contexts/              # React Context providers
│   │   └── UserProfileContext.tsx # Global user profile state
│   │
│   ├── hooks/                 # Custom React hooks
│   │   └── useJobs.ts         # Job loading & matching logic
│   │
│   ├── lib/                   # Core business logic
│   │   ├── matching.ts       # Career Fit Index (CFI) calculation
│   │   ├── dataLoader.ts     # CSV parsing & job normalization
│   │   ├── roadmapGenerator.ts # Roadmap generation logic
│   │   ├── resumeParser.ts   # Resume parsing utilities
│   │   └── storage.ts         # LocalStorage persistence
│   │
│   ├── data/                  # Static data databases
│   │   ├── skillsDatabase.ts  # 200+ skills taxonomy
│   │   └── rolesDatabase.ts  # 100+ roles with skill requirements
│   │
│   └── types/                 # TypeScript type definitions
│       └── index.ts           # All shared types
│
├── datasets/                  # CSV job data files
│   ├── master_jobs.csv       # Consolidated job list (preferred)
│   └── [other sources].csv
│
└── public/                    # Static assets
    └── datasets/              # Public CSV files (served to client)

For detailed architecture documentation, see CODEBASE_STRUCTURE.md

---

🧮 Key Algorithms

Career Fit Index (CFI)

The CFI is a composite score that measures how well a job matches a user's profile:

CFI = (Skill Fit Index × weight) + (Relevance Index × weight)

Default weights: 50% Skill Fit, 50% Relevance (user-adjustable)

Skill Fit Index (SFI)

Compares user skill proficiency vs job requirements:

SFI = (1/N) × Σ min(1, Y/X) × 100

Where:

• N = total number of skills required
• X = required proficiency level (1-10)
• Y = user's proficiency level (1-10)

Relevance Index (RI)

Measures alignment with user's target role:

RI = 100 × (0.50 × CategoryMatch + 0.25 × ExactRoleMatch + 0.25 × SkillsMatch)

• Category Match (50%): Job category vs target role category
• Exact Role Match (25%): Job title vs target role
• Target Role Skills Match (25%): Job skills vs target role skills

Skill Matching

• Normalization: Handles skill name variations (e.g., "React.js" = "React")
• Proficiency Scoring: Compares user score (1-10) vs required score (1-10)
• Alias Resolution: Uses skills database to match variations

---

🔐 Environment Variables

Variable	Required	Description
OPENAI_API_KEY	Yes	OpenAI API key for resume parsing and roadmap generation
NEXTAUTH_URL	Optional	Base URL for NextAuth (default: http://localhost:3000)
NEXTAUTH_SECRET	Optional	Secret key for NextAuth session encryption
GOOGLE_CLIENT_ID	Optional	Google OAuth client ID for Gmail integration
GOOGLE_CLIENT_SECRET	Optional	Google OAuth client secret for Gmail integration

---

📖 Usage

First Time Setup

1. Onboarding

   • Upload your resume (DOCX, PDF, or TXT)
   • Upload your transcript (optional)
   • Review and edit extracted information
   • Set your target role
   • Configure job preferences

2. Find Jobs

   • Browse personalized job listings
   • Use filters to narrow down results
   • Click on jobs to see detailed match breakdown
   • Save interesting jobs to your tracker

3. Track Applications

   • Move applications through stages using drag & drop
   • Connect Gmail for automatic status updates
   • Add interview/OA/offer details manually
   • Export events to calendar

4. Learning Roadmap

   • Select your target role
   • Set time and budget constraints
   • Generate AI-powered learning roadmap
   • Track progress as you complete tasks

Tips

• Update Your Profile: Keep your skills and proficiency scores up to date
• Use Filters: Narrow down jobs by industry, location, salary, etc.
• Adjust CFI Weights: Prioritize skill fit or relevance based on your goals
• Track Everything: Use the tracker to stay organized during your job search
• Follow Roadmaps: Complete roadmap tasks to bridge skill gaps

---

💻 Development

Available Scripts

# Development server
npm run dev

# Production build
npm run build

# Start production server
npm start

# Lint code
npm run lint

Code Structure

• Components: Reusable UI components in src/components/
• Hooks: Custom React hooks in src/hooks/
• Lib: Core business logic in src/lib/
• Types: TypeScript definitions in src/types/
• API Routes: Backend endpoints in src/app/api/

Key Files

• src/lib/matching.ts - Core matching algorithm (CFI calculation)
• src/hooks/useJobs.ts - Job loading and matching logic
• src/contexts/UserProfileContext.tsx - Global user profile state
• src/lib/dataLoader.ts - CSV parsing and job normalization
• src/app/api/parse-resume/route.ts - AI resume parsing endpoint

Adding New Features

1. New Component: Add to src/components/
2. New Hook: Add to src/hooks/
3. New API Route: Add to src/app/api/
4. New Type: Add to src/types/index.ts
5. New Utility: Add to src/lib/

---

📚 Documentation

• CODEBASE_STRUCTURE.md - Detailed architecture and codebase structure
• PROJECT_WRITEUP.md - Comprehensive project documentation

---

🎯 Key Features Summary

Feature	Description
🤖 AI Parsing	Automatically extract skills, experience, and education from resumes
🎯 Smart Matching	Career Fit Index (CFI) algorithm matches jobs to your profile
📊 Application Tracker	Kanban board to track applications through all stages
📧 Gmail Integration	Auto-detect status updates from emails
🗺️ Learning Roadmaps	AI-generated personalized learning paths
👤 Profile Management	Comprehensive profile with skill proficiency tracking
🔍 Advanced Filtering	Filter jobs by multiple criteria
📅 Calendar Sync	Export interviews and deadlines to calendar

---

🤝 Contributing

This is a personal project, but suggestions and feedback are welcome!

---

📄 License

This project is private and proprietary.

---

🙏 Acknowledgments

• OpenAI for GPT-4o-mini API
• Next.js team for the amazing framework
• All job platforms for providing data sources

---

📞 Support

For questions or issues, please refer to the documentation files or check the codebase structure.

---

Built with ❤️ for job seekers in Singapore