JobHunter: building a job-search agent that has to explain itself
An automated agent that collects openings from 12 public sources, scores them against every user's profile deterministically, and delivers matches via Telegram — why I chose explainable rules over an LLM.
Job hunting in Ethiopia means manually re-searching the same scattered job boards and Telegram channels every day — and a large share of the listings you find are already dead. JobHunter is my answer: a multi-user agent that continuously collects openings from public boards and Telegram channels, normalizes and deduplicates them, scores every job against every user's profile, and delivers the matches that matter via Telegram or a web inbox.
This post is about the decisions that shaped it — and the trade-offs I consciously accepted.
Decision 1: deterministic scoring, not an LLM
The obvious 2026 move is to hand a job description and a CV to an LLM and ask "how good is this match?" I didn't, for three reasons:
- A score you can't explain is a score candidates can't act on. "73% match" is useless; "matches 6 of 8 required skills, has React → Next.js transferability at 0.9, missing the seniority bar for one responsibility" is something a person can verify and act on.
- Tests. The engine runs in CI. If a scoring change regresses matching quality, one of 515 tests catches it. You cannot put an LLM call inside a deterministic regression suite and expect stable results.
- Cost and latency at fan-out. The matcher runs per-user per-job. With hundreds of jobs per collection cycle and multiple users, that's thousands of evaluations — for free, in-process, in milliseconds with rules.
The engine is driven by a versioned knowledge base rather than hardcoded heuristics: skill aliases, categories, a transferability graph, prerequisites, role profiles (core vs common vs advanced skills), seniority levels, and negative signals. A slice of the real implementation:
/**
* Get the transferability score from skill A to skill B.
* Returns 0 if not transferable, 0-1 otherwise.
*/
export function getTransferability(from: string, to: string): number {
// Direct transferability lookup
if (TRANSFERABILITY[from]?.[to]) return TRANSFERABILITY[from][to];
// Reverse lookup
if (TRANSFERABILITY[to]?.[from]) return TRANSFERABILITY[to][from];
// Via relationship weight
...
}
So "2 years of Node.js + TypeScript, applying to a NestJS role" doesn't score as zero — the knowledge base encodes that NestJS is learnable from that base at a known weight. The trade-off: rules can't catch fuzzy, context-dependent matches an LLM might. I accepted that in exchange for explainability and testability, and the knowledge base is data — it improves version by version without touching the engine.
Decision 2: one canonical job, however many boards posted it
The same opening routinely appears on three boards and two Telegram channels. Showing it five times destroys trust in the inbox, so the pipeline groups duplicates into one canonical job. The trade-off here is asymmetric: a wrong merge is worse than a duplicate. A duplicate costs one extra glance; a wrongly merged job can hide a different role at the same company. So the merge rules are deliberately conservative — strong identity signals must agree before two listings collapse into one.
Decision 3: SQLite, single node, on purpose
The authoritative store is SQLite behind Prisma. Not Postgres, not a managed cluster. The system is single-node by design, which buys: zero-ops persistence, file-level backups, and transactional simplicity for the background workers. The cost is a hard ceiling on horizontal scale — and that's fine, because the product's unit of scale is "one user's matches," not "millions of rows per second." Postgres schema variants exist in the repo for the day that changes. Choosing a boring database is the feature.
Decision 4: polite collection, honest index
Collectors run on a budget: rate-limited requests, per-source adapters, FAST and DEEP sweep modes. Two integrity sweeps keep the index trustworthy:
- Ghost-job detection — a listing that misses three consecutive collection cycles is retired.
- Link-rot detection — a daily sweep validates apply URLs and flags dead ones.
The trade-off is speed: aggressive scraping would index faster. It would also get this project's IP addresses banned from the sources it depends on, and serve users listings they can't actually apply to. Correctness of the index beats freshness by a day.
Each source lives in its own adapter class (Ethiojobs, Remotive, ReliefWeb, Arbeitnow, Jobicy, RemoteOK, and more, plus Telegram channels). Scrapers are the most fragile code in any system — job boards redesign, RSS feeds move. Isolating that fragility per adapter means a broken source is a one-file fix, never a pipeline outage.
Decision 5: approval binds to the exact content reviewed
The newest phase (Phase 8) handles the last mile: applying. The system builds a versioned application package from the candidate's verified profile data. The candidate then works on an editable draft of that package — but here's the part I care about most: every edit creates an immutable revision, and approval records a content hash bound to the exact revision the candidate reviewed.
ApplicationPackage (immutable, from verified profile data)
└── ApplicationDraft (editable candidate copy)
└── DraftRevision (immutable, every edit)
└── Approval (binds to one revision's content hash)
The trade-off is storage and schema complexity — revisions are never updated, only appended. In exchange, "what exactly did the candidate approve?" always has a provable answer. For a system whose output is a job application on someone's behalf, that's the semantics I want.
A small NFR with a measured payoff
One change I'm fond of because it's measurable: the root route was a client component that redirected to /dashboard after hydration. Every visitor downloaded the shell bundle to learn where they should be. A Next.js middleware now reads the session cookie server-side and redirects before any HTML ships. On Lighthouse's simulated 3G profile that took first paint from 5.3s to effectively instant for returning users, and there's a Playwright regression spec to keep it that way.
export function middleware(req: NextRequest) {
const dest = req.cookies.has('jh_token') ? '/dashboard' : '/login';
return NextResponse.redirect(new URL(dest, req.url));
}
Results and honest limits
Where it stands: 515 tests across 40 suites, Playwright e2e coverage including the low-bandwidth routing path, CI on every push, and a matching engine whose every score shows its evidence.
What it isn't: horizontally scalable (single-node by choice), and Telegram-dependent for instant delivery (the web inbox is the fallback so no match is ever silently lost). Scrapers will break again — the adapter pattern makes that a contained, expected cost rather than an outage.
The bet underneath all of it: for matching decisions that affect people's livelihoods, an explainable system you can test beats a magical one you can't.