JobHunterAI is a production-grade, local-first ecosystem designed to automate the modern job search. By leveraging a high-performance Python backend with a multi-tier AI fallback router and a modern React frontend, it provides job seekers with enterprise-level tools for resume optimization, job discovery, and application tracking.
JobHunterAI has transitioned to a fully Decoupled Service Model for maximum maintainability.
- ResumeService: Logic for ATS matching, tailoring, and high-fidelity parsing.
- InterviewService: Dedicated service for contextual question generation and behavioral STAR feedback.
- JobService: Live multi-platform discovery and enrichment fleet.
- GeneratorService: Optimized for document drafting (Cover Letters, Outreach).
The system implements a verified N-Tier Routing logic:
- Tier 1 (Groq): Ultra-fast Llama 3.3 for real-time tailoring.
- Tier 2 (Gemini): High-reasoning 1.5 Flash for complex context.
- Tier 3 (Local): Sentence-Transformers or Ollama for absolute privacy and offline fallback.
Utilizes a YAML-based registry (config/apify_actors.yaml) to orchestrate a parallel fleet of scrapers (LinkedIn, Indeed, Google Jobs) with automated health monitoring and priority selection.
Utilizes a YAML-based registry (config/apify_actors.yaml) to manage a fleet of Apify actors (LinkedIn, Indeed, Google Jobs) with automated health monitoring and priority-based selection.
graph TD
subgraph Client Layer
Web[React Dashboard]
end
subgraph API Gateway
FastAPI[FastAPI Service]
Policer[Request Policer]
Sanitizer[PII Redactor]
end
subgraph Intelligence Core
Router[3-Tier Smart Router]
ResumeEngine[Resume V2]
Coach[AI Interview Coach]
ScraperFleet[Job Discovery]
Analytics[Mission Control]
end
subgraph Data Layer
Cache[(Response Cache)]
DB[(SQLite / Postgres)]
end
Web --> FastAPI
FastAPI --> Policer
Policer --> Sanitizer
Sanitizer --> Cache
Cache -- Miss --> Router
Router --> ResumeEngine & Coach & ScraperFleet & Analytics
ResumeEngine & Coach & ScraperFleet & Analytics --> DB
- 3-Tier Smart AI Router: Dynamically routes tasks based on capability and health. Supports
automode to automatically switch between Groq, Gemini, and local models. - AI Interview Coach: Practice mock interviews with real-time scoring and STAR method guidance grounded in your resume.
- Production Resume Builder: Multi-document management with 10 professional A4 templates and high-fidelity PDF/DOCX exports.
- Recruiter CRM: Discover Hiring Managers and Recruiters via live intelligence and manage outreach history.
- Intelligent Job Discovery: Aggregated live job feeds from LinkedIn and Glassdoor with automated deduplication and AI enrichment.
- Unified Mission Control: Career dashboard with chronological timelines, success rates, and skill-gap radar.
- Zero-Trust Privacy: Integrated PII redactor masks sensitive data locally before any cloud processing.
- Python 3.11+
- Node.js 22+
- PostgreSQL (Optional, defaults to SQLite)
- External Services: Groq (Recommended), Apify (For cloud scraping)
# Clone the repository
git clone https://github.com/your-org/JobHunterAI.git
cd JobHunterAI
# Setup Backend
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r backend/requirements.txt
python -m playwright install chromium
# Setup Frontend
cd frontend
npm install
npm run build
cd ..Copy .env.example to .env and fill in your API keys:
cp .env.example .env| Variable | Default | Description |
|---|---|---|
ENVIRONMENT |
development |
development, production, testing, staging |
PORT |
8000 |
API server port |
AI_PROVIDER |
auto |
Primary AI engine (auto, groq, gemini, openai, ollama) |
GROQ_API_KEY |
- | Required for Tier 1 inference |
GEMINI_API_KEY |
- | Required for Tier 2 inference |
DATABASE_URL |
sqlite+aiosqlite:///./jobhunter.db |
SQLAlchemy connection string |
APIFY_API_TOKEN |
- | Required for premium job board scraping |
CORS_ORIGINS |
* |
Allowed origins (CSV or JSON array) |
For production, set ENVIRONMENT=production and specify explicit CORS_ORIGINS.
# Start Backend
python backend/main.py
# Start Frontend (in separate terminal)
cd frontend
npm run devWe use Alembic for version-controlled schema updates:
cd backend
$env:PYTHONPATH="..;../core" # Windows
python -m alembic upgrade head$env:PYTHONPATH=".;core"
python -m pytest tests/unit tests/applicationdocker-compose up --build -dbackend/: FastAPI routers and API entry points.frontend/: React components and dashboard UI.core/: Business logic, AI engine, and database infrastructure.domain/: Pure domain entities and value objects.application/: Use cases and orchestration services.docs/: Technical guides and architecture records.tests/: Multi-level test suite (Unit, Integration, E2E).
- Backend: FastAPI, SQLAlchemy 2.0, Pydantic, Alembic
- Frontend: React 18, TypeScript, Tailwind CSS, Lucide React
- AI/ML: Groq (Llama 3.3), Google Gemini, Ollama, Sentence-Transformers
- Data: PostgreSQL, SQLite, Pandas
- Export: Playwright (PDF), python-docx, Markdown
Contributions are welcome! Please read the Contributing Guide before submitting a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.
If you encounter issues, check the Support Guide or open a GitHub Issue.
- Port Conflict: Change
PORTin.envif 8000 is occupied. - AI Failures: Verify your API keys in
.env. - Scraper Errors: Ensure
playwrightis installed viapython -m playwright install.