jobhunter-cli 0.1.0__tar.gz

jobhunter_cli-0.1.0/.env.example

@@ -0,0 +1,6 @@
+# Telegram: create a bot at https://t.me/BotFather and get the bot token, then start a chat with your bot and get the chat ID.
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=
+
+# OpenAI: create an account at https://platform.openai.com/ and generate an API key.
+LLM_API_KEY=

jobhunter_cli-0.1.0/.github/workflows/job-maintenance.yml

@@ -0,0 +1,78 @@
+name: Job Maintenance & Discovery
+
+on:
+  schedule:
+    # Runs once a week: every Sunday at 3:00 AM UTC
+    - cron: '0 3 * * 0'
+  workflow_dispatch:
+    inputs:
+      source:
+        description: 'Run discovery/prune for a specific source only (optional)'
+        type: string
+        required: false
+        default: ''
+
+jobs:
+  maintenance:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up UV and Python
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+          cache: "uv"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run Discover and Prune if config.json exists
+        run: |
+          if [ ! -f "config/config.json" ]; then
+            echo "config/config.json does not exist. Skipping maintenance tasks."
+            exit 0
+          fi
+
+          SOURCE_FLAG=""
+          if [ "${{ github.event_name }}" == "workflow_dispatch" ] && [ -n "${{ inputs.source }}" ]; then
+            SOURCE_FLAG="--source ${{ inputs.source }}"
+          fi
+
+          echo "Running discovery..."
+          uv run jobhunter discover --write $SOURCE_FLAG
+
+          echo "Running pruning..."
+          uv run jobhunter prune --write $SOURCE_FLAG
+
+      - name: Commit and push updated config.json
+        run: |
+          if [ ! -f "config/config.json" ]; then
+            exit 0
+          fi
+
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git status
+
+          if [ -f "config/config.json" ]; then
+            git add config/config.json
+          fi
+
+          if git diff --staged --quiet; then
+            echo "No changes in config.json to commit."
+          else
+            git commit -m "chore(maintenance): update company board configuration [skip ci]"
+            git push
+          fi

jobhunter_cli-0.1.0/.github/workflows/job-pipeline.yml

@@ -0,0 +1,139 @@
+name: Job Pipeline
+
+on:
+  schedule:
+    # 1. First daily run (Aggregators ENABLED)
+    - cron: "0 6 * * *"
+    # 2. Subsequent daily runs (Aggregators DISABLED)
+    - cron: "0 14,22 * * *"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Run pipeline in dry-run mode (no telegram notifications sent)"
+        type: boolean
+        required: false
+        default: false
+      ignore_seen:
+        description: "Ignore seen history cache and re-process recent jobs"
+        type: boolean
+        required: false
+        default: false
+      no_aggregators:
+        description: "Disable aggregator sources (Remotive, RemoteOK, Arbeitnow)"
+        type: boolean
+        required: false
+        default: true
+      source:
+        description: "Run for a specific source/company only (optional)"
+        type: string
+        required: false
+        default: ""
+      limit:
+        description: "Limit maximum candidates per run (optional)"
+        type: number
+        required: false
+        default: 0
+
+jobs:
+  run-pipeline:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up UV and Python
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Check existing state files before run
+        id: check-state
+        run: |
+          if [ -f "data/candidates.json" ]; then
+            echo "candidates_exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "candidates_exists=false" >> $GITHUB_OUTPUT
+          fi
+          if [ -f "data/evaluated.json" ]; then
+            echo "evaluated_exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "evaluated_exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run JobHunter Pipeline
+        env:
+          TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
+          TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
+          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+          CONFIG_JSON: ${{ secrets.CONFIG_JSON }}
+          CV: ${{ secrets.CV }}
+          PREFERENCES: ${{ secrets.PREFERENCES }}
+        run: |
+          CMD="uv run jobhunter run"
+
+          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
+            if [ "${{ inputs.no_aggregators }}" == "true" ]; then
+              CMD="$CMD --no-aggregators"
+            fi
+            if [ "${{ inputs.dry_run }}" == "true" ]; then
+              CMD="$CMD --dry-run"
+            fi
+            if [ "${{ inputs.ignore_seen }}" == "true" ]; then
+              CMD="$CMD --ignore-seen"
+            fi
+            if [ -n "${{ inputs.source }}" ]; then
+              CMD="$CMD --source ${{ inputs.source }}"
+            fi
+            if [ -n "${{ inputs.limit }}" ] && [ "${{ inputs.limit }}" -gt 0 ]; then
+              CMD="$CMD --limit ${{ inputs.limit }}"
+            fi
+          elif [ "${{ github.event_name }}" == "schedule" ]; then
+            if [ "${{ github.event.schedule }}" == "0 6 * * *" ]; then
+              echo "Morning schedule triggered: Aggregators ENABLED"
+            else
+              echo "Subsequent schedule triggered: Aggregators DISABLED"
+              CMD="$CMD --no-aggregators"
+            fi
+          fi
+
+          echo "Executing: $CMD"
+          eval $CMD
+
+      - name: Commit and push state files
+        env:
+          CANDIDATES_EXISTS: ${{ steps.check-state.outputs.candidates_exists }}
+          EVALUATED_EXISTS: ${{ steps.check-state.outputs.evaluated_exists }}
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git status
+
+          git add data/seen.json
+
+          if [ "$CANDIDATES_EXISTS" == "true" ] && [ -f "data/candidates.json" ]; then
+            git add data/candidates.json
+          fi
+
+          if [ "$EVALUATED_EXISTS" == "true" ] && [ -f "data/evaluated.json" ]; then
+            git add data/evaluated.json
+          fi
+
+          if git diff --staged --quiet; then
+            echo "No state file changes to commit."
+          else
+            git commit -m "chore(pipeline): update jobhunter state files [skip ci]"
+            git push
+          fi

jobhunter_cli-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.locks
+logs
+todo.txt
+
+# Virtual environments
+.venv
+
+# Secrets and personal files
+.env
+config/*
+!config/.gitkeep
+
+# Generated by the tool. Only data/seen.json is meant to be committed (the GitHub Actions workflow does it).
+data/*
+!data/.gitkeep
+!data/seen.json

jobhunter_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

jobhunter_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ziad Aboughaleb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jobhunter_cli-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: jobhunter-cli
+Version: 0.1.0
+Summary: An AI-powered, zero-database Python CLI that automates job hunting. It scrapes ATS boards, evaluates candidate-job fit using LLMs against your CV, and dispatches real-time Telegram alerts.
+Author-email: ziad-aboughaleb <ziadaboughaleb@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: ddgs>=9.16.1
+Requires-Dist: filelock>=4.2.4
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: openai>=3.41.0
+Requires-Dist: pydantic-settings>=2.16.1
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.27.3
+Description-Content-Type: text/markdown
+
+# JobHunter 🎯
+
+> **AI-Powered, Highly Concurrent, Zero-Database Automated Job Hunting Pipeline**
+
+`JobHunter` is a robust, production-grade Python CLI application designed to fully automate the job search and filtering lifecycle. It continuously scrapes Applicant Tracking Systems (ATS) and job boards, filters opportunities against precise regex and keyword criteria, evaluates candidate-job fit using Large Language Models (LLMs) with strict JSON schemas, and dispatches rich real-time alerts directly to Telegram.
+
+---
+
+## 🚀 Key Features
+
+- **High Concurrency & Rate Limiting**: Powered by `concurrent.futures` with dynamic worker bounds, exponential backoff retries on transient network errors, and intelligent request pacing.
+- **ATS WAF & API Bypass**: Bypasses heavy frontend anti-bot walls by querying official public underlying JSON/XML board APIs directly (Greenhouse, Lever, Personio, Workable, Recruitee, Ashby, plus aggregators like Remotive, RemoteOK, and Arbeitnow).
+- **Multi-Stage Filtering**: Filters jobs through regex word-boundary matching for titles, excluded companies, location rules, remote requirements, posting age, and minimum tech stack keyword hits (`stack_hits`).
+- **AI-Driven Evaluation**: Evaluates shortlisted candidates against your exact CV (`config/cv.md`) and preferences (`config/preferences.md`) using OpenAI-compatible LLMs, enforcing hard gates, scoring rubrics, and anti-hallucination guardrails.
+- **Telegram Rich Alerts**: Dispatches beautifully formatted HTML notifications featuring VIP priority badges, score color-coding, AI reasoning, score breakdowns, professional pitches, and direct links.
+- **Autonomous Maintenance Tools**: Includes built-in CLI commands to automatically discover new company career boards via DuckDuckGo and prune dead or broken board URLs.
+- **Zero-Database State Management**: Uses atomic file writes with file locking (`filelock`) and a rolling 90-day retention cache (`seen.json`) to prevent duplicate processing without requiring an external database.
+
+---
+
+## 🛠️ Quickstart Guide
+
+### Prerequisites
+
+- **Python >= 3.14**
+- **uv** (recommended Python package and project manager)
+
+### 1. Clone & Install
+
+```bash
+git clone https://github.com/ziad-aboughaleb/job-hunter-v2.git
+cd job-hunter-v2
+uv sync
+```
+
+### 2. Configure Environment Variables
+
+Copy the example environment file and add your API keys:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
+TELEGRAM_CHAT_ID=your_telegram_chat_id_here
+LLM_API_KEY=your_openai_or_compatible_api_key_here
+```
+
+### 3. Set Up Configuration & Profile
+
+Create or copy configuration files in the `config/` directory (examples are provided in `examples/`):
+
+```bash
+cp examples/config.example.json config/config.json
+cp examples/preferences.example.md config/preferences.md
+# Create your cv.md in config/
+cp examples/cv.example.json config/cv.md # (rename or write as Markdown)
+```
+
+> **💡 Note on Environment Fallbacks & GitHub Actions:**
+> `JobHunter` automatically falls back to environment variables (`CONFIG_JSON`, `CV`, `PREFERENCES`) if physical configuration files do not exist on disk. This allows deploying via GitHub Actions on public repositories using GitHub Secrets instead of committing sensitive files.
+
+### 4. Run the Pipeline
+
+Execute the full pipeline (Fetch -> Evaluate -> Send):
+
+```bash
+uv run jobhunter run
+```
+
+---
+
+## 🔄 The 5-Stage Pipeline
+
+```
+[Discover / Configure] ──> [Fetch & Filter] ──> [AI Evaluate] ──> [Send to Telegram] ──> [State Purge & Seen Sync]
+```
+
+1. **Discover / Configure**: Resolve targets from `config.json` or discover new company boards using `jobhunter discover`.
+2. **Fetch**: Scrape raw job postings concurrently across configured ATS boards and aggregators.
+3. **Filter & Prune**: Discard duplicates, previously seen jobs, and postings failing title, location, age, or stack keyword criteria. Rank candidates by VIP priority and stack keyword hits.
+4. **Evaluate**: Submit shortlisted candidates to the LLM. Enforce hard gates and score against your CV and preferences.
+5. **Send & Purge**: Dispatch passing job alerts to Telegram. Log processed jobs to `seen.json` with a 90-day retention window and purge completed items from active state files.
+
+---
+
+## 📖 Documentation Deep Dives
+
+For comprehensive technical documentation, consult the `docs/` folder:
+
+- **[Architecture Guide](docs/architecture.md)**: Detailed breakdown of the decoupled pipeline modules, concurrency model, and zero-database state lifecycle.
+- **[Configuration & Settings](docs/configuration.md)**: Comprehensive guide to `config.json`, Pydantic settings, environment variables, and prompt engineering setup (`cv.md` / `preferences.md`).
+
+---
+
+## 💻 CLI Commands Reference
+
+| Command              | Description                                           | Key Options                                                                     |
+| :------------------- | :---------------------------------------------------- | :------------------------------------------------------------------------------ |
+| `jobhunter run`      | Runs the full pipeline (fetch -> evaluate -> send)    | `-s, --source`, `--no-aggregators`, `--ignore-seen`, `-l, --limit`, `--dry-run` |
+| `jobhunter fetch`    | Scrapes and filters jobs from configured boards       | `-s, --source`, `--no-aggregators`, `--ignore-seen`, `-l, --limit`              |
+| `jobhunter evaluate` | Scores and evaluates pending candidates using AI      | `-j, --job <UID>`, `-l, --limit`                                                |
+| `jobhunter send`     | Dispatches passing job evaluations to Telegram        | `--dry-run`                                                                     |
+| `jobhunter discover` | Discovers new company ATS slugs via DuckDuckGo        | `-w, --write`, `-s, --source`, `-t, --titles`                                   |
+| `jobhunter prune`    | Validates and prunes broken company slugs from config | `-w, --write`, `-s, --source`                                                   |
+| `jobhunter prompt`   | Prints the compiled AI evaluation system prompt       | None                                                                            |

jobhunter_cli-0.1.0/README.md

@@ -0,0 +1,109 @@
+# JobHunter 🎯
+
+> **AI-Powered, Highly Concurrent, Zero-Database Automated Job Hunting Pipeline**
+
+`JobHunter` is a robust, production-grade Python CLI application designed to fully automate the job search and filtering lifecycle. It continuously scrapes Applicant Tracking Systems (ATS) and job boards, filters opportunities against precise regex and keyword criteria, evaluates candidate-job fit using Large Language Models (LLMs) with strict JSON schemas, and dispatches rich real-time alerts directly to Telegram.
+
+---
+
+## 🚀 Key Features
+
+- **High Concurrency & Rate Limiting**: Powered by `concurrent.futures` with dynamic worker bounds, exponential backoff retries on transient network errors, and intelligent request pacing.
+- **ATS WAF & API Bypass**: Bypasses heavy frontend anti-bot walls by querying official public underlying JSON/XML board APIs directly (Greenhouse, Lever, Personio, Workable, Recruitee, Ashby, plus aggregators like Remotive, RemoteOK, and Arbeitnow).
+- **Multi-Stage Filtering**: Filters jobs through regex word-boundary matching for titles, excluded companies, location rules, remote requirements, posting age, and minimum tech stack keyword hits (`stack_hits`).
+- **AI-Driven Evaluation**: Evaluates shortlisted candidates against your exact CV (`config/cv.md`) and preferences (`config/preferences.md`) using OpenAI-compatible LLMs, enforcing hard gates, scoring rubrics, and anti-hallucination guardrails.
+- **Telegram Rich Alerts**: Dispatches beautifully formatted HTML notifications featuring VIP priority badges, score color-coding, AI reasoning, score breakdowns, professional pitches, and direct links.
+- **Autonomous Maintenance Tools**: Includes built-in CLI commands to automatically discover new company career boards via DuckDuckGo and prune dead or broken board URLs.
+- **Zero-Database State Management**: Uses atomic file writes with file locking (`filelock`) and a rolling 90-day retention cache (`seen.json`) to prevent duplicate processing without requiring an external database.
+
+---
+
+## 🛠️ Quickstart Guide
+
+### Prerequisites
+
+- **Python >= 3.14**
+- **uv** (recommended Python package and project manager)
+
+### 1. Clone & Install
+
+```bash
+git clone https://github.com/ziad-aboughaleb/job-hunter-v2.git
+cd job-hunter-v2
+uv sync
+```
+
+### 2. Configure Environment Variables
+
+Copy the example environment file and add your API keys:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
+TELEGRAM_CHAT_ID=your_telegram_chat_id_here
+LLM_API_KEY=your_openai_or_compatible_api_key_here
+```
+
+### 3. Set Up Configuration & Profile
+
+Create or copy configuration files in the `config/` directory (examples are provided in `examples/`):
+
+```bash
+cp examples/config.example.json config/config.json
+cp examples/preferences.example.md config/preferences.md
+# Create your cv.md in config/
+cp examples/cv.example.json config/cv.md # (rename or write as Markdown)
+```
+
+> **💡 Note on Environment Fallbacks & GitHub Actions:**
+> `JobHunter` automatically falls back to environment variables (`CONFIG_JSON`, `CV`, `PREFERENCES`) if physical configuration files do not exist on disk. This allows deploying via GitHub Actions on public repositories using GitHub Secrets instead of committing sensitive files.
+
+### 4. Run the Pipeline
+
+Execute the full pipeline (Fetch -> Evaluate -> Send):
+
+```bash
+uv run jobhunter run
+```
+
+---
+
+## 🔄 The 5-Stage Pipeline
+
+```
+[Discover / Configure] ──> [Fetch & Filter] ──> [AI Evaluate] ──> [Send to Telegram] ──> [State Purge & Seen Sync]
+```
+
+1. **Discover / Configure**: Resolve targets from `config.json` or discover new company boards using `jobhunter discover`.
+2. **Fetch**: Scrape raw job postings concurrently across configured ATS boards and aggregators.
+3. **Filter & Prune**: Discard duplicates, previously seen jobs, and postings failing title, location, age, or stack keyword criteria. Rank candidates by VIP priority and stack keyword hits.
+4. **Evaluate**: Submit shortlisted candidates to the LLM. Enforce hard gates and score against your CV and preferences.
+5. **Send & Purge**: Dispatch passing job alerts to Telegram. Log processed jobs to `seen.json` with a 90-day retention window and purge completed items from active state files.
+
+---
+
+## 📖 Documentation Deep Dives
+
+For comprehensive technical documentation, consult the `docs/` folder:
+
+- **[Architecture Guide](docs/architecture.md)**: Detailed breakdown of the decoupled pipeline modules, concurrency model, and zero-database state lifecycle.
+- **[Configuration & Settings](docs/configuration.md)**: Comprehensive guide to `config.json`, Pydantic settings, environment variables, and prompt engineering setup (`cv.md` / `preferences.md`).
+
+---
+
+## 💻 CLI Commands Reference
+
+| Command              | Description                                           | Key Options                                                                     |
+| :------------------- | :---------------------------------------------------- | :------------------------------------------------------------------------------ |
+| `jobhunter run`      | Runs the full pipeline (fetch -> evaluate -> send)    | `-s, --source`, `--no-aggregators`, `--ignore-seen`, `-l, --limit`, `--dry-run` |
+| `jobhunter fetch`    | Scrapes and filters jobs from configured boards       | `-s, --source`, `--no-aggregators`, `--ignore-seen`, `-l, --limit`              |
+| `jobhunter evaluate` | Scores and evaluates pending candidates using AI      | `-j, --job <UID>`, `-l, --limit`                                                |
+| `jobhunter send`     | Dispatches passing job evaluations to Telegram        | `--dry-run`                                                                     |
+| `jobhunter discover` | Discovers new company ATS slugs via DuckDuckGo        | `-w, --write`, `-s, --source`, `-t, --titles`                                   |
+| `jobhunter prune`    | Validates and prunes broken company slugs from config | `-w, --write`, `-s, --source`                                                   |
+| `jobhunter prompt`   | Prints the compiled AI evaluation system prompt       | None                                                                            |

jobhunter_cli-0.1.0/docs/architecture.md

@@ -0,0 +1,115 @@
+# Architecture & Pipeline Deep Dive
+
+`JobHunter` is engineered as a decoupled, highly concurrent, zero-database Python pipeline. This document provides a deep architectural breakdown of its modules, state management lifecycle, and concurrency model.
+
+---
+
+## 🏗️ Core Module Architecture
+
+The application logic is organized into clean, single-responsibility modules located in `src/jobhunter/`:
+
+```
+src/jobhunter/
+├── main.py             # Typer CLI entrypoint and command router
+├── models.py           # Pydantic data models (Job, Candidate, EvaluationResult, EvaluatedCandidate)
+├── core/
+│   ├── filters.py      # Regex word-boundary filters and scoring utilities
+│   ├── http.py         # Robust HTTP client with retries and exponential backoff
+│   ├── logger.py       # Rich console and logging configuration
+│   ├── paths.py        # Atomic file I/O, path resolution, and file locking
+│   ├── settings.py     # Pydantic Settings & configuration loading
+│   └── textutil.py     # HTML cleaning and date parsing utilities
+├── pipeline/
+│   ├── evaluate.py     # Stage 4: AI evaluation via OpenAI/LLM API
+│   ├── fetch.py        # Stage 1-3: Scraping, filtering, deduplication, and scoring
+│   └── send.py         # Stage 5: Telegram dispatch and state lifecycle management
+├── sources/
+│   ├── arbeitnow.py    # Arbeitnow aggregator source adapter
+│   ├── ashby.py        # Ashby ATS board source adapter
+│   ├── base.py         # Base ATS scraper & slug validator
+│   ├── greenhouse.py   # Greenhouse ATS board source adapter
+│   ├── lever.py        # Lever ATS board source adapter
+│   ├── personio.py     # Personio ATS board source adapter
+│   ├── recruitee.py    # Recruitee ATS board source adapter
+│   ├── remoteok.py     # RemoteOK aggregator source adapter
+│   ├── remotive.py     # Remotive aggregator source adapter
+│   └── workable.py     # Workable ATS board source adapter
+└── tools/
+    ├── discover.py     # DuckDuckGo-powered company ATS board discovery
+    ├── prompt.py       # Compiled system prompt inspection tool
+    └── prune.py        # Automated dead board validation and pruning
+```
+
+### 1. Fetch & Filter Pipeline (`fetch.py`)
+
+- **Task Generation**: Iterates through registered sources (`SOURCES`), matching non-aggregator sources with company slugs defined in `config.json` (e.g., `companies.greenhouse = ["stripe"]`). Aggregators (Remotive, RemoteOK, Arbeitnow) operate without slugs.
+- **Concurrent Scraping**: Dispatches fetch tasks across a `ThreadPoolExecutor` bounded by `settings.workers.fetch_workers`.
+- **Filtering & Deduplication**: Passes raw `Job` instances through `passes_all_filters()` (checking title include/exclude, company exclusions, location rules, remote requirements, posting age, and minimum stack hits). Removes cross-source duplicates and jobs already recorded in `seen.json`.
+- **Prioritization & Capping**: Ranks passing jobs by VIP priority status (`company_priority`) and stack keyword hits (`stack_hits`). Enforces `max_candidates_per_run` and atomically writes the resulting candidates to `data/candidates.json`.
+
+### 2. AI Evaluation Pipeline (`evaluate.py`)
+
+- **Task Loading & Filtering**: Reads `data/candidates.json` and `data/evaluated.json`, isolating pending candidates not yet evaluated. Supports evaluating specific candidates via `--job <UID>` or overriding run candidate limits via `--limit <INT>`.
+- **Structured LLM Calls & Resilient Retries**: Submits each candidate along with the compiled system prompt to the OpenAI-compatible LLM client (`response_format={"type": "json_object"}`). Features automatic exponential backoff retries on transient network errors, rate limits (`RateLimitError`, 429), and server errors (`APIStatusError`, 5xx).
+- **Validation & Fallback Parsing**: Parses and validates LLM responses against the `EvaluationResult` Pydantic model, with built-in markdown block cleanup (`json ... `) and fallback parsing. On schema validation failure, logs offending raw JSON for easy debugging.
+- **Concurrency & Persistence**: Executes evaluation tasks across `settings.workers.evaluation_workers`, sorts successfully evaluated candidates by match score descending, and atomically persists them to `data/evaluated.json`.
+
+### 3. Telegram Dispatch & State Management (`send.py`)
+
+- **Dispatch**: Loads evaluated candidates from `evaluated.json` where `evaluation.hard_fail` is `False`. Formats rich HTML messages (including priority badges, score emojis, reasoning, score explanation, pitch, and job URL) and sends them to Telegram via `httpx` with 1-second request pacing.
+- **State Lifecycle & Pruning**: Upon successful processing:
+  1. Records all evaluated job UIDs into `data/seen.json` mapped to their current Unix timestamp (`int(time.time())`).
+  2. Executes a **90-day retention prune** on `seen.json`, discarding any entry older than `settings.limits.seen_retention_days * 86400` seconds to prevent file bloat.
+  3. Purges processed UIDs from `data/candidates.json`.
+  4. Cleans up `evaluated.json` (preserving any items that failed delivery).
+
+### 4. Discovery Tool (`discover.py`)
+
+- Queries DuckDuckGo (`site:{domain} "{title}"`) for active company career boards across supported ATS providers (Greenhouse, Lever, Ashby, Personio, Workable, Recruitee).
+- Extracts company slugs using regular expression patterns.
+- Concurrently validates discovered slugs against ATS APIs. If run with `--write`, automatically merges valid new slugs into `config/config.json`. Includes a circuit breaker triggering after 3 consecutive search errors.
+
+### 5. Pruning Tool (`prune.py`)
+
+- Reads configured company slugs from `config/config.json`.
+- Concurrently validates each slug against ATS APIs. Treats 404 and 410 HTTP status codes as definitive dead links (`SlugStatus.INVALID`).
+- If run with `--write`, removes broken slugs from `config/config.json`.
+
+### 6. Source Adapters (`sources/`)
+
+- **Lightweight API-First Design**: `JobHunter` entirely avoids heavy, resource-intensive headless browsers (such as Selenium or Playwright) by querying public, lightweight JSON and XML ATS APIs directly. This ensures lightning-fast execution, minimal memory footprint, and high concurrency.
+- **Aggregators vs. ATS Board Scrapers**:
+  - **Aggregators** (`remotive.py`, `remoteok.py`, `arbeitnow.py`): Pull global remote job feeds without requiring company slugs (`is_aggregator = True`).
+  - **ATS Board Scrapers** (`greenhouse.py`, `lever.py`, `ashby.py`, `personio.py`, `workable.py`, `recruitee.py`): Fetch job openings specifically via company board slugs (e.g., Greenhouse API endpoint `https://boards-api.greenhouse.io/v1/boards/{slug}/jobs`).
+- **Slug Validation & Lifecycle (`validate_slug`)**: Both the `discover` and `prune` tools inherit from `BaseSource` and utilize the `validate_slug(slug)` method. By executing lightweight test queries or checking HTTP status codes (where 404 and 410 represent definitive dead links), `validate_slug` returns a `SlugStatus` enum (`VALID`, `INVALID`, or `UNKNOWN`) to ensure all tracked boards remain active.
+
+---
+
+## 🔄 State Management Lifecycle
+
+`JobHunter` maintains state entirely in flat JSON files within the `data/` directory, protected against race conditions and concurrent execution anomalies:
+
+```
+[candidates.json] ──(Evaluated)──> [evaluated.json] ──(Sent & Synced)──> [seen.json (90-day retention)]
+```
+
+- **`data/candidates.json`**: Active pool of filtered, un-evaluated candidates waiting for AI scoring.
+- **data/evaluated.json**: Storage for candidates that have undergone AI evaluation.
+- **data/seen.json**: Persistent dictionary mapping job unique identifiers (`uid`) to their discovery/processing timestamp (`{uid: timestamp}`). Prevents re-scraping or re-evaluating the same job across runs, bounded by a 90-day rolling window.
+- **Concurrency & Atomic Safety (`paths.py`)**: All write operations utilize `filelock.FileLock` (using lockfiles stored in `.locks/`) combined with atomic replacement (`tempfile.mkstemp` + `os.replace` + `os.fsync`/`fdatasync`), ensuring zero file corruption even under high concurrency or abrupt termination.
+
+---
+
+## ⚡ Concurrency & Rate-Limiting Model
+
+`JobHunter` leverages Python's `concurrent.futures.ThreadPoolExecutor` for maximum concurrency while respecting API rate limits:
+
+- **Configurable Worker Bounds**: Each pipeline stage reads worker allocations from `settings.workers`, strictly clamped between 1 and 20 threads (discovery clamped to 10):
+  - `fetch_workers` (default: 8)
+  - `evaluation_workers` (default: 1)
+  - `discovery_workers` (default: 8)
+  - `pruning_workers` (default: 8)
+- **Exponential Backoff**: HTTP requests (`http.py`) automatically retry transient errors (HTTP 408 Request Timeout, 429 Too Many Requests, and 5xx Server Errors) with exponential backoff (`backoff * (2 ** attempt)`).
+- **Request Pacing**:
+  - LLM requests include an optional configurable delay (`settings.llm.request_delay`, default 5s).
+  - Telegram dispatches include a fixed 1-second delay (`time.sleep(1)`) to comply with Telegram Bot API rate limits (1 message/second per chat).