JobTool - Intelligent Job Application Tracker

An intelligent, full-stack job application tracking system that automates the entire job search workflow from discovery to status monitoring. Built for software engineering internship seekers who want to streamline their application process and never miss opportunities.

Who This Is For

• Software Engineering Students seeking internships and entry-level positions
• Job Seekers who want to automate application tracking and status monitoring
• Developers looking for a comprehensive solution to manage their job search pipeline
• Anyone tired of manually tracking hundreds of job applications across multiple platforms

Why JobTool Was Built

The modern job search process is overwhelming:

• Information Overload: 50+ new job postings daily from newsletters like SWEList
• Manual Tracking: Spreadsheets become unmanageable with hundreds of applications
• Status Confusion: Email updates scattered across threads, hard to correlate with applications
• Lost Opportunities: Missing follow-ups or status changes buried in email

JobTool solves these problems by providing complete automation from job discovery to final status tracking.

Key Features

Automated Job Discovery

• Email Scraping: Automatically extracts jobs from SWEList daily newsletters
• Smart Parsing: Uses Cheerio to parse HTML job listings with company, position, and application URLs
• Duplicate Prevention: Two-tier system prevents duplicate entries while allowing valid variations

Gmail Integration with OAuth2

• Secure Authentication: Full OAuth2 implementation with Google APIs
• Real-time Monitoring: Monitors Gmail every 30 minutes for status updates
• Email Classification: Automatically categorizes emails (rejections, interviews, offers)
• Thread Association: Links status emails to original job applications

Intelligent Status Updates

• Automatic Recognition: Detects application confirmations, rejections, interview invitations, and offers
• Smart Matching: Associates incoming emails with existing job applications using advanced matching algorithms
• Status Pipeline: Tracks complete journey: posted → applied → oa_round → interview → rejected/offer/ghosted

Modern React Frontend

• Drag & Drop Interface: Intuitive Kanban-style board using @dnd-kit
• Real-time Updates: Live status changes with optimistic UI updates
• Advanced Filtering: Filter by status, date ranges, and company
• Detailed Views: Comprehensive job details with full email history

Comprehensive Tracking

• Complete Audit Trail: Every status change and email interaction logged
• Date Tracking: Automatic date applied calculation when status changes
• Email History: Full email thread preservation for context
• Search & Filter: Find specific applications instantly

Tech Stack

Frontend

• React 19 with TypeScript - Modern, type-safe UI development
• Tailwind CSS - Utility-first styling for responsive design
• @dnd-kit - Smooth drag-and-drop interactions
• React Hooks - Modern state management patterns

Backend

• Node.js with Express 5 - High-performance REST API
• MongoDB with Mongoose - Flexible document database with ODM
• Gmail API - Official Google APIs integration
• OAuth2 - Secure Google authentication

Automation & Monitoring

• Node-Cron - Scheduled job scraping (daily at 4:00 PM CDT)
• PM2 Process Manager - Production-grade process management
• Cheerio - Server-side HTML parsing for job extraction
• Real-time Email Monitoring - 30-minute intervals for status updates

DevOps & Deployment

• PM2 Ecosystem - Multi-process management with auto-restart
• Windows Services - Auto-startup configuration for production
• Structured Logging - Date-stamped logs in job_logs/ directory
• Error Handling - Comprehensive retry logic and graceful degradation

Architecture Overview

Three-Service Architecture

1. Web Application (server.js) - REST API and static file serving on port 3001
2. Job Scheduler (cronScheduler.js) - Daily email scraping at 4:00 PM CDT
3. Email Monitor (emailMonitor.js) - Continuous Gmail monitoring every 30 minutes

Data Flow

SWEList Email → Gmail API → Job Parser → Duplicate Check → Database
                     ↓
Status Emails → Email Classifier → Job Matcher → Status Updater → Database
                     ↓
Frontend ← REST API ← Database

Smart Duplicate Prevention

• In-Memory Cache: company + position + location key for same-session deduplication
• Database Unique Index: company + position + applicationUrl for persistent deduplication
• Allows Valid Variations: Same company/position with different locations or URLs

Security & Authentication

OAuth2 Implementation

• Google APIs Integration: Full OAuth2 flow with refresh token management
• Scope Limitation: Read-only Gmail access (gmail.readonly)
• Secure Token Storage: Encrypted token persistence with automatic refresh
• Credential Management: Secure client secret handling

Data Security

• No Secret Logging: All sensitive data excluded from logs
• Local Processing: All email parsing happens locally, no external AI services
• Secure Database: MongoDB with proper connection string handling
• Environment Variables: Sensitive configuration via .env files

Getting Started

Prerequisites

• Node.js (v16+)
• MongoDB (local or cloud)
• Gmail Account with API access enabled
• Google Cloud Project with Gmail API enabled

Installation

# Clone the repository
git clone https://github.com/armaanamatya/jobtool.git
cd jobtool

# Install dependencies
npm install

# Configure Gmail OAuth2
# 1. Create Google Cloud Project
# 2. Enable Gmail API
# 3. Create OAuth2 credentials
# 4. Download client_secret_*.json to project root

# Authenticate with Gmail
node scripts/authenticate.js

# Start development environment
npm run dev  # Starts both frontend and backend

Production Deployment

# Start all services with PM2
pm2 start ecosystem.config.js

# Install as Windows service (auto-startup)
setup-autostart.bat

Available Commands

Development

• npm start - React development server (port 3000)
• npm run server - Express API server (port 3001)
• npm run dev - Full development environment
• npm test - Run React test suite

Job Processing

• npm run scraper - One-time job scraping
• npm run scheduler - Start daily scheduler (4:00 PM CDT)
• node scripts/startEmailMonitor.js - Start Gmail monitoring

Production

• pm2 start ecosystem.config.js - Production deployment
• setup-autostart.bat - Windows service installation

Database Schema

Job Document

{
  company: String,           // Company name
  position: String,          // Job title
  status: String,           // posted, applied, oa_round, interview, rejected, offer, ghosted
  datePosted: Date,         // When job was discovered
  dateApplied: Date,        // When application was submitted
  applicationUrl: String,   // Direct application link
  location: String,         // Job location (optional)
  salaryRange: String,      // Salary information (optional)
  statusHistory: [{         // Complete audit trail
    status: String,
    date: Date,
    source: String          // 'manual', 'email', 'automatic'
  }],
  emailHistory: [{          // Associated emails
    messageId: String,
    subject: String,
    snippet: String,
    receivedDate: Date,
    emailType: String       // 'application', 'rejection', 'interview', 'offer'
  }],
  emailThreadId: String,    // Gmail thread association
  notes: String,            // User notes
  isActive: Boolean,        // Soft delete flag
  lastUpdated: Date         // Auto-updated timestamp
}

Process Management

The system runs three independent processes managed by PM2:

1. jobtool-server - Main web application and API
2. jobtool-scheduler - Daily job scraping (restarts daily at midnight)
3. jobtool-email-monitor - Gmail monitoring (restarts every 6 hours)

Each process includes comprehensive error handling, automatic restarts, and structured logging.

Future Enhancements

• Excel Export - Export application data to spreadsheets
• Sankey Diagrams - Visual application flow analysis
• AI Integration - Intelligent job matching and recommendations
• Multi-source Scraping - Support for additional job boards
• Mobile App - React Native mobile companion

Contributing

This project demonstrates modern full-stack development practices:

• TypeScript for type safety
• Clean Architecture with separation of concerns
• Comprehensive Logging for debugging and monitoring
• Error Handling with graceful degradation
• Automated Testing capabilities
• Production-Ready deployment configuration

Contact

Built by Armaan Amatya - GitHub

---

JobTool showcases expertise in full-stack development, API integration, automation, and modern web technologies. Perfect for demonstrating real-world problem-solving skills to potential employers.