HeadHunter

The stack is FastAPI + Uvicorn, with the root route serving frontend/index.html and static assets. JobScraper pulls from sources defined in config.py (GitHub internship lists, Indeed, LinkedIn, Glassdoor, WayUp, etc., enabled per ENABLED_SOURCES). Internship mode prioritizes GitHub-sourced listings to avoid brittle anti-bot pages; other sites use requests, BeautifulSoup, rotating fake_useragent headers, and configurable delays. After collection, jobs are filtered and ranked by keyword overlap, then written through Database to jobs.db with fields such as title, company, location, description, source, remote flags, and extracted skills.

Search vs refresh POST /api/search queries existing rows via get_jobs_by_criteria; it does not scrape on every keystroke. A force_refresh flag schedules scraper.scrape_jobs as a FastAPI BackgroundTasks job so ingestion happens asynchronously.

Resume and matching GeminiResumeParser (see gemini_resume_parser.py) uses Gemini 1.5 Flash with a JSON-schema-style prompt to extract skills, experience years, technologies, education, certifications, and confidence. POST /api/upload-resume accepts uploads; POST /api/resume-job-match aligns that structured profile to stored jobs. Saved listings use /api/jobs/{id}/save, /api/saved-jobs, and DELETE to unsave.

Operations A cache_manager backs optional caching; /api/cache/stats, clear, and clear-expired expose maintenance. /api/stats and POST /api/refresh support monitoring and bulk refresh. Environment variables cover GEMINI_API_KEY, DB path, host/port, scrape delays, and rate limits; Docker and production Uvicorn deployment are documented in the repo.

Entry and routing: main.py mounts CORS, instantiates Database, JobScraper, and GeminiResumeParser, and registers JSON APIs for search, job CRUD-style reads, saved jobs, resume upload and matching, target-field jobs, refresh endpoints, and cache. Static files are served for the SPA-like frontend.

Scraper internals: job_scraper.py implements per-source handlers (e.g. GitHub internship JSON/HTML), merges results, deduplicates, applies salary/remote/experience filters from Config, and ranks by relevance to supplied keywords. Selenium was removed in favor of HTTP parsing for Python 3.13 compatibility.

Testing: The tests/ suite covers app routes, resume upload, search, scraping modes, and Gemini integration (see README for pytest commands).