Job Sentinel

Local-first career platform: multi-source job search, AI profile↔job match, application tracker, and ATS-tuned résumé generation, all on your own hardware.

🌐 Live demo · 📚 Docs · 📦 Releases

Job Sentinel watches your university job portals, aggregates listings from public job APIs, tracks your applications, and generates ATS-ready résumés and cover letters tailored to each role, entirely on your own machine. No API keys required for the defaults, no data leaving your hardware.

It ships with adapters for UTD 12twenty and Handshake, four no-key job sources (RemoteOK, The Muse, Arbeitnow, Himalayas), two opt-in keyed sources (Adzuna, USAJobs), company-board fetchers (Greenhouse/Lever/Ashby), and a multi-provider LLM layer you can point at Ollama, OpenRouter, Groq, Gemini, or OpenAI. Adding a new portal adapter takes one file and ~50 lines of Python.

🌐 Hosted demo vs. running locally: the live demo shows the interface, but the engine (scraping, local AI, PDF builds) runs on your machine by design: your portal credentials, your data, and the model never leave it. Follow the Quick Start below to run the real thing, about 5 minutes.

⚡ One-command setup

git clone https://github.com/harshitwandhare/job-sentinel && cd job-sentinel
bash scripts/install.sh        # macOS / Linux  (Windows: powershell -ExecutionPolicy Bypass -File scripts\install.ps1)
job-sentinel web               # API + web UI at http://localhost:3000

There's also a clip-to-track browser extension: one click on any job posting (LinkedIn, Greenhouse, Lever, Indeed…) drops it straight into your tracker.

📸 What it looks like

Dashboard: pipeline, deadlines, source health	Find jobs anywhere: multi-source search + filters
Your profile is your résumé, rendered live, exports to ATS PDF	Application tracker: saved → applied → offer
Résumé studio: tailor + ATS score against any JD	Settings: bring your own LLM (or local Ollama)

_{Screens shown with the bundled demo dataset. Run locally for your real jobs, profile, and a private model.}

🧭 Why this exists

The 2026 job market is brutal for students: the average opening now draws ~242 applications (3× the 2021 volume), 93% of seekers have applied to a ghost job, and two-thirds have been rejected by an AI screen without a human ever reading their résumé. The edge that's left: apply early (watch portals, don't scroll them) and apply matched (ATS-clean documents tailored to each posting).

Every mainstream tool that helps with this is cloud SaaS, so your résumé, your application history, and the jobs you're chasing live on someone else's servers, behind a freemium meter. Job Sentinel is the same loop with the opposite architecture:

One integrated pipeline, watch → alert → track → tailor → apply: typed, tested, and free, on hardware you already own.

✨ Features

🏗 Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                             Job Sentinel                                │
│                                                                         │
│  ┌──────────────┐   ┌───────────────┐   ┌──────────────────────────┐   │
│  │   Scheduler  │──▶│  SiteAdapter  │──▶│     JobRepository        │   │
│  │ (APScheduler)│   │  (Playwright) │   │  (sqlite-utils, SQLite)  │   │
│  └──────┬───────┘   └───────────────┘   │  job_postings            │   │
│         │                               │  applications            │   │
│         ▼                               │  generated_documents     │   │
│  ┌──────────────┐                       └──────────────────────────┘   │
│  │  Notifiers   │  ┌────────────────────────────────────────────────┐  │
│  │ Telegram/    │  │              FastAPI (local API)               │  │
│  │ Email        │  │  profile · jobs · match · applications ·       │  │
│  └──────────────┘  │  documents · sources · llm/config · ops        │  │
│                    └────────────────┬───────────────────────────────┘  │
│  ┌──────────────┐                   │                                  │
│  │ Job Sources  │                   ▼                                  │
│  │ (HTTP/JSON)  │   ┌──────────────────────────────────────────────┐  │
│  │ RemoteOK     │   │         Next.js Web UI (localhost:3000)      │  │
│  │ The Muse     │   │  dashboard · search · applications · resumes │  │
│  │ Arbeitnow    │   │  settings · jobs · profile · studio · chat   │  │
│  │ Himalayas    │   └──────────────────────────────────────────────┘  │
│  │ Adzuna …     │                                                      │
│  └──────────────┘   ┌──────────────────────────────────────────────┐  │
│                     │     LLM Provider Layer (documents/providers)  │  │
│  ┌──────────────┐   │  OllamaBackend · OpenAICompatClient           │  │
│  │ Company ATS  │   │  (OpenAI / OpenRouter / Groq / Gemini /      │  │
│  │ Greenhouse   │   │   custom) · build_chat_backend/embed_backend  │  │
│  │ Lever · Ashby│   └──────────────────────────────────────────────┘  │
│  └──────────────┘                                                      │
└─────────────────────────────────────────────────────────────────────────┘

See docs/design/HLD.md for the full High-Level Design and docs/design/LLD.md for Low-Level Design.

🚀 Quick Start

1. Prerequisites

• Python 3.11+
• uv (install: curl -LsSf https://astral.sh/uv/install.sh | sh)
• A Telegram account

2. Clone & Install

git clone https://github.com/harshitwandhare/job-sentinel.git
cd job-sentinel

# Install all dependencies (creates .venv automatically)
uv sync

# Install Playwright's Chromium browser
uv run playwright install chromium

3. Create your Telegram bot

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts → copy the token
3. Message your new bot once, then visit: https://api.telegram.org/bot<TOKEN>/getUpdates
4. Copy your chat ID from the JSON response (message.chat.id)

4. Configure

cp .env.example .env
# Edit .env and fill in:
#   TELEGRAM_BOT_TOKEN=...
#   TELEGRAM_CHAT_ID=...
#   PORTAL_USERNAME=your_utd_netid
#   PORTAL_PASSWORD=your_password

5. Sign in once (Cloudflare-gated portals)

uv run job-sentinel login     # a browser opens; credentials prefill from .env,
                              # clear the challenge, click Sign In, done
uv run job-sentinel session   # verify: "✓ Session valid as <your name>"

⚠️ Don't add a viewId=<n> parameter to PORTAL_JOBS_URL: saved-search views can be "not authorized" for your account, which silently renders an empty list (the classic "scrape found 0 jobs" trap).

6. Test run (dry run: no messages sent)

uv run job-sentinel scrape

7. Start the full bot

uv run job-sentinel run

That's it. Open Telegram and send /start to your bot.

⚙️ Configuration

All configuration is via environment variables in .env. See .env.example for the full reference.

🤖 Bot Commands

📄 Résumé Generator

Job Sentinel keeps a universal profile: your master CV data in one hand-editable YAML file, and renders ATS-friendly PDFs from it. It's standalone: you don't need the Telegram bot configured to use it.

# 1. Scaffold a profile you can edit like an Overleaf source
uv run job-sentinel resume init        # writes data/profile.yaml

# 2. Edit data/profile.yaml: add education, experience, projects, skills…

# 3. Build an ATS-friendly PDF (also writes the .tex next to it)
uv run job-sentinel resume build -o data/resume.pdf
uv run job-sentinel resume show        # summarise your profile

# 4. Tailor to a specific posting: reorders content by relevance and
#    reports ATS keyword coverage (matched vs missing terms)
uv run job-sentinel resume build --job-text "paste a job description here"
uv run job-sentinel resume build --job-id <posting_id>   # a posting already scraped

# 5. Generate a tailored cover letter (deterministic, or --ai to polish locally)
uv run job-sentinel resume cover --job-text "…" --role "Student Assistant" --company "UTD"

PDF rendering uses Tectonic (a self-contained LaTeX engine, no full TeX install needed). Install it once:

winget install TectonicProject.Tectonic   # Windows
brew install tectonic                      # macOS
cargo install tectonic                     # Linux (or your package manager)

If Tectonic isn't installed, resume build still writes the .tex so you can compile it on Overleaf. The template is single-column with standard fonts and real selectable text, so it parses cleanly through ATS.

Optional: local-LLM rephrasing (no API key)

Add --ai to rephrase your bullets toward a posting using a local model via Ollama: fully offline, no API key, your data never leaves your machine. It only rephrases content already in your profile (it can't invent facts), and falls back to keyword tailoring if the model isn't available.

job-sentinel resume doctor --pull      # checks Ollama + pulls the model
job-sentinel resume build --ai --job-text "paste a job description"

AI providers (bring your own key)

Ollama is the zero-config default: no account, no key, fully offline. You can swap either the chat model or the embeddings model for any cloud provider (OpenRouter, Groq, Gemini, OpenAI) via the Settings page at http://localhost:3000/settings or by setting env vars in .env. Free tiers exist for OpenRouter, Groq, and Gemini. Groq is fast but does not support embeddings, so pair it with Gemini or Ollama for that slot.

See docs/llm-providers.md for the full reference: env var names, per-provider setup, graceful-degradation behaviour, and the privacy/security posture.

🖥 Web UI

Prefer a UI? Job Sentinel ships a local web app (Next.js + Tailwind) over a FastAPI layer: same engine, nicer surface. It's fully local: the API binds to localhost and the optional LLM stays on your machine.

# One command for everything: API + UI + recurring scrape watcher
uv run job-sentinel web --watch        # http://localhost:3000

# Or piecemeal:
job-sentinel serve                     # API only; Swagger at /docs
cd web && npm install && npm run dev   # UI only

The ⌘K command palette (CommandPalette) is always available for fast navigation. Hosted-demo mode (NEXT_PUBLIC_DEMO=1) populates every screen with realistic sample data so visitors can explore without a running backend.

Jobs board: real scraped postings, one-click tailored documents	Résumé studio: paste a JD, get ATS coverage + a one-page PDF

Sharing your instance (optional auth)

Want a public demo of your instance, or to invite a friend? Turn on authentication, stdlib-only, no services:

job-sentinel users add yourname --admin   # first account must be an admin
AUTH_MODE=demo job-sentinel serve          # reads public, actions need login

AUTH_MODE=demo keeps browsing open but gates actions; required gates everything. Admins create further accounts (users add, or POST /api/auth/users). Details in docs/deployment.md.

🔌 Adding a New Portal

1. Create src/job_sentinel/adapters/sites/my_portal.py
2. Subclass SiteAdapter, implement login() and scrape_page()
3. Set SITE_ADAPTER=my_portal in your .env

Full guide: docs/design/adapter-authoring.md

🛠 Development

# Install dev dependencies
uv sync --all-extras

# Install pre-commit hooks (runs ruff, mypy, secret scan on every commit)
uv run pre-commit install

# Run tests
uv run pytest

# Lint & format
uv run ruff check --fix .
uv run ruff format .

# Type check
uv run mypy src/

# All at once (same as CI)
uv run pre-commit run --all-files

🐳 Deployment (always-on) & data persistence

Run it continuously with Docker. The image is based on the official Playwright image (Chromium + system libs included):

docker compose up -d --build     # start detached
docker compose logs -f           # follow

Your data never vanishes on restart. ./data and ./logs are bind-mounted from the host, so the SQLite database, captured login session, and your profile live on disk, surviving container restarts, rebuilds, and reboots.

12twenty's login is Cloudflare-gated, so capture a session on the host first with job-sentinel login (it writes data/session.json, which the container mounts and reuses). Re-run login if the session expires.

Backups. Everything important is in data/. Back it up while the bot is idle, for example a WAL-safe SQLite copy:

sqlite3 data/jobs.db ".backup data/jobs.backup.db"
cp data/profile.yaml data/profile.backup.yaml

📁 Project Structure

job-sentinel/
├── src/job_sentinel/
│   ├── adapters/              # Plugin system: base interface, registry,
│   │   └── sites/             #   12twenty + Handshake adapters
│   ├── api/                   # FastAPI layer: routes, ops runner, auth, chat
│   ├── bot/                   # Telegram command handlers
│   ├── config/                # pydantic-settings config + loguru setup
│   ├── core/                  # Browser, models (JobPosting/Application/
│   │                          #   GeneratedDocument), scheduler, session, text
│   ├── db/                    # sqlite-utils repository (schema v2)
│   ├── documents/             # Resume engine: LaTeX, tailoring, LLM,
│   │                          #   embeddings, cover letters, PDF import,
│   │                          #   providers (ChatBackend/EmbedBackend), match
│   ├── notifiers/             # Telegram (MarkdownV2) + SMTP email
│   ├── profile/               # Universal profile models + YAML store
│   ├── sources/               # Pluggable job-source layer: JobSource ABC,
│   │                          #   registry, aggregate_search; RemoteOK / The Muse /
│   │                          #   Arbeitnow / Himalayas / Adzuna / USAJobs / JobSpy;
│   │                          #   company_boards (Greenhouse/Lever/Ashby)
│   └── __main__.py            # Typer CLI entry-point
├── web/                       # Next.js UI (App Router, Tailwind, vitest)
│   ├── app/                   # page.tsx per route (landing, dashboard, search,
│   │                          #   applications, resumes, settings, jobs, profile,
│   │                          #   studio, chat, login)
│   ├── components/            # AiMatch, DataTable, SearchResultCard, JobsExplorer,
│   │                          #   ResumePaper, CommandPalette, Nav, ScraperControls…
│   └── lib/                   # api.ts (typed client), demo.ts (NEXT_PUBLIC_DEMO)
├── tests/                     # unit/ · integration/ · e2e/ (450+ tests)
├── docs/                      # MkDocs site: HLD, LLD, ADRs, llm-providers,
│                              #   compliance, deployment, NORTH_STAR
├── .github/workflows/         # CI · Release · Docs · Scorecard
├── pyproject.toml             # Single source of truth (uv + hatchling)
└── uv.lock                    # Reproducible builds (CI uses --locked)

📋 Roadmap

• Résumé engine (universal profile → ATS LaTeX/PDF) with per-posting tailoring
• Local-LLM rephrasing via Ollama (no API key)
• Web UI (Next.js) + local FastAPI layer: full CLI feature parity
• Email notifier (optional SMTP) alongside Telegram
• Deadline-aware tracking (/deadlines)
• Docker / docker-compose with persistent data
• Cover-letter generation (deterministic + local-LLM polish)
• Semantic relevance ranking (local embeddings via Ollama)
• Resume PDF import → structured profile draft
• Session validity checks + credential-prefilled login
• Optional multi-user auth (demo/required modes, admin invites)
• Hosted demo (Vercel) + docs site (GitHub Pages): both $0
• Multi-source job search: RemoteOK, The Muse, Arbeitnow, Himalayas, Adzuna, USAJobs, JobSpy; Greenhouse/Lever/Ashby company boards (see ADR 005)
• BYO-LLM providers: OpenAI, OpenRouter, Groq, Gemini alongside Ollama; configurable from Settings UI (see docs/llm-providers.md)
• AI profile↔job match: blended ATS + semantic + grounded LLM rationale (POST /api/match)
• Application tracker: full CRUD pipeline (saved → interviewing → offer/rejected), CLI + API + web
• Document library: persisted generated résumés and cover letters with ATS scores
• Dashboard: funnel stats, recent activity, quick actions
• ⌘K command palette
• Deeper ATS scoring: parser-style simulation of the big enterprise ATSes, beyond keyword coverage
• Ghost-job signals: flag stale/repost patterns before you sink hours in
• Application analytics: funnel stats over your own history (response rates by employer, day-of-week, match score)
• Discord webhook notifier
• Playwright e2e suite against job-sentinel web
• Packaged installers + PyPI publish

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

All commits must follow Conventional Commits. Run uv run pre-commit install to enforce this automatically.

👤 Author

Built and maintained by Harshit Wandhare: a CS student who got tired of the 2026 job grind and decided to engineer a way through it. If this project is useful, a ⭐ helps; if you're hiring, I'd love to talk.

• GitHub: @harshitwandhare
• LinkedIn: in/harshit-wandhare

📄 License

MIT © Harshit Wandhare: see LICENSE.