Home

Point it at the job boards you follow. It reads every new listing and tells you which ones fit your resume.

Repository · Website · Latest release

Job Matcher is a self-hosted AI job search tool. It watches the careers pages, ATS boards and web searches you choose, filters new listings by location, experience and title, and asks an LLM to judge each remaining job against your resume. Matches are saved, tracked as you apply, and can be posted to Discord. Everything runs on your own machine with Docker Compose; your resume and data never leave it except for the scraping and LLM calls you configure.

This wiki is the technical reference for the project: how it is built, how it behaves, how it looks, and how to run, change and ship it. The README remains the short introduction.

Start here

If you want to…	Read
Install and use the app	Getting Started → Configuration Reference
Understand how it works	Architecture → Run Pipeline → AI Matching
Work on the code	Development Setup → Repository Layout → Contributing
Design or change the UI	Visual System → Design Tokens → Components → Brand
Run it in production	Deployment → Troubleshooting

Contents

Using Job Matcher

• Getting Started: requirements, the one-line installers, demo and live mode, a first run.
• Configuration Reference: every environment variable and every per-user setting.
• Troubleshooting: symptoms, causes and fixes.

System design

• Architecture: services, process boundaries, request and run flow, design decisions.
• Backend API: NestJS modules and the full HTTP endpoint reference.
• Authentication: better-auth, sessions, the first-party proxy and origin rules.
• Data Model: every Prisma model, relations, indexes and the migration history.

The matching engine

• Run Pipeline: a run from button press to saved match, statuses and the typed error model.
• Job Sources and Scraping: ATS adapters, page and search sources, Firecrawl modes and hybrid routing.
• Firecrawl Credits and Caching: the credit reserve, daily allowance, page cache and context keys.
• AI Matching: listing extraction, title triage, evaluation, OpenRouter routing and cost controls.

Interface and brand

• Frontend: Next.js routes, data layer, polling and onboarding.
• Visual System: the design language, type, colour, layout, states and accessibility.
• Design Tokens: every CSS custom property and Tailwind theme token.
• Components: UI primitives and app-level components.
• Brand: the mark, lockups, colour, type and icon pipeline.
• Marketing Site: the static site in site/ and its GitHub Pages deployment.

Engineering

• Development Setup: local environment, scripts, hooks, linting and type-checking.
• Repository Layout: an annotated map of the monorepo.
• Testing: unit, integration and end-to-end tests, and the coverage gate.
• CI/CD and Releases: GitHub Actions, multi-arch images and the release procedure.
• Deployment: Docker images, the Compose stack, HTTPS, backups and upgrades.
• Contributing: workflow, commit style, stacked PRs and where to add things.
• Glossary: the project's vocabulary.

At a glance

flowchart LR
  browser([Browser]) --> web[Next.js web app]
  web -- "/api proxy" --> api[NestJS API]
  api --> pg[(PostgreSQL)]
  api -- "enqueue run" --> redis[(Redis / BullMQ)]
  redis --> worker[Run worker]
  worker --> pg
  worker --> firecrawl[Firecrawl]
  worker --> openrouter[OpenRouter]
  worker --> discord[Discord webhook]

Loading

Layer	Technology
Runtime and language	Bun, TypeScript (strict)
Frontend	Next.js 16, React 19, Tailwind CSS 4
Backend	NestJS, Effect, better-auth
Data	PostgreSQL 17 with Prisma, Redis 8 with BullMQ
AI and scraping	OpenRouter (structured JSON output), Firecrawl (cloud, self-hosted or hybrid)
Quality	Biome, Bun test, Playwright, GitHub Actions
Delivery	Docker multi-stage builds, Docker Compose, multi-arch images on GHCR

About this wiki

The pages describe the code on the master branch, and source links point there. When the code and a page disagree, the code is right; please fix the page. To edit the wiki locally:

git clone https://github.com/Karthik-beta/AI-Job-Resume-Matcher.wiki.git

Images used by the wiki live in its images/ folder; they are copies of docs/screenshots/ and docs/brand/ in the main repository.

Job Matcher is released under the MIT license.