JD Matcher is an intelligent job matching tool that leverages Large Language Model (LLM) capabilities to find the most suitable jobs based on user resumes and job descriptions. The project provides services through a Telegram bot, automatically crawling job listings and notifying users when matching positions are found.

• 🤖 Intelligent Matching: Uses LLM-based embeddings (OpenRouter) for vector representations and DeepSeek for semantic matching
• 📱 Telegram Bot Integration: grammY-powered bot with pagination, file upload, and inline keyboards
• 🕷️ Automated Job Crawling: Supports RemoteOK and WeWorkRemotely job sources with scheduled crawling
• 🔔 Smart Notifications: Automatically notifies users when matching jobs are found via Telegram and email
• 📧 Email Verification: Users can set and verify their email for email-based job notifications
• ⚡ Cloud-Native: Built on Cloudflare Workers with D1 database, Vectorize search, Queue-based async jobs, and Container-based agent runtime
• 🚀 Fully Serverless: No infrastructure to manage, auto-scaling with Containers for long-running workloads

jd-matcher/
├── src/
│   ├── index.ts               # Entry: Hono routes + scheduled() + queue()
│   ├── lib/
│   │   ├── types.ts           # All type definitions + Env bindings
│   │   ├── db/                # D1 CRUD (job_detail, user_info, user_matched_job, email_verification)
│   │   ├── llm/               # OpenRouter embeddings + DeepSeek chat + prompt
│   │   ├── crawler/           # RemoteOK + WeWorkRemotely scrapers
│   │   ├── email/             # Email HTML/text templates
│   │   └── vectorize/         # Vectorize upsert/query helpers
│   ├── container/
│   │   ├── server.ts          # HTTP server wrapping runMatchAgent for Container runtime
│   │   └── server.test.ts     # Integration tests
│   ├── bot/
│   │   ├── bot.ts             # grammY setup + env middleware + command registration
│   │   ├── session.ts         # KV-backed chat session (10min TTL)
│   │   ├── constants.ts       # All Telegram reply texts
│   │   └── handlers/          # start, help, all_jobs, jobs, upload_resume, expectation
│   └── jobs/
│       ├── crawl.ts           # Fetch jobs from RemoteOK + WeWorkRemotely
│       ├── embed.ts           # Generate embeddings → store in Vectorize
│       ├── match.ts           # Vector search → AI agent (Vercel AI SDK) → store matches
│       ├── match.test.ts
│       └── notify.ts          # Unnotified matches → Telegram + email
├── migrations/
│   ├── 001_initial.sql        # D1 schema
│   └── 002_email_verification.sql  # Email verification table
├── wrangler.toml              # Single config — D1, KV, Vectorize, Queue, Cron
├── package.json
└── tsconfig.json

Cron        ──▶  scheduled()  ──▶  JOBS_QUEUE.send({type})  ──▶  queue() → dispatch
Telegram    ──▶  Hono POST /telegram/webhook  ──▶  grammY bot  ──▶  command handlers
Match agent ──▶  MatchContainer (Cloudflare Containers)  ──▶  runMatchAgent (Vercel AI SDK)

• Node.js 20+ (for local development)
• Wrangler CLI (npx wrangler)
• Cloudflare account
• Telegram Bot Token (from @BotFather)
• OpenRouter API Key
• DeepSeek API Key

1. Clone the repository

   git clone https://github.com/chenjunqian/jd-matcher.git
   cd jd-matcher

2. Install dependencies

   npm install

3. Set up Cloudflare resources

   # Create D1 database
   npx wrangler d1 create jd-matcher-db
   
   # Copy the database_id from output into wrangler.toml
   
   # Run migration
   npx wrangler d1 execute jd-matcher-db --file migrations/001_initial.sql
   
   # Run email verification migration
   npx wrangler d1 execute jd-matcher-db --file migrations/002_email_verification.sql
   
   # Create KV namespace
   npx wrangler kv:namespace create "SESSION_KV"
   # Copy id into wrangler.toml [[kv_namespaces]]
   
   # Create Vectorize indexes
   npx wrangler vectorize create job-desc-embeddings --dimensions=1024 --metric=cosine
   npx wrangler vectorize create resume-embeddings --dimensions=1024 --metric=cosine
   
   # Create job queue
   npx wrangler queue create jd-jobs-pool

4. Set secrets

   npx wrangler secret put TELEGRAM_BOT_TOKEN
   npx wrangler secret put LLM_OPENROUTER_APIKEY
   npx wrangler secret put LLM_DEEPSEEK_APIKEY

5. Deploy

   npx wrangler deploy

   Note: The MatchContainer requires a Dockerfile at the project root. The container image is built and deployed automatically with wrangler deploy.

6. Set Telegram webhook

   curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://jd-matcher.<subdomain>.workers.dev/telegram/webhook"

# Start local dev server with bindings
npx wrangler dev

# Register webhook for local testing (requires tunnel)
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://your-tunnel.ngrok.io/telegram/webhook"

1. Resume Upload: Users upload their resumes as text files through the Telegram bot
2. Vector Embedding: Resumes are converted to vector representations using OpenRouter embeddings
3. Job Crawling: Cron triggers crawl jobs from RemoteOK and WeWorkRemotely every 2 hours
4. Embedding Generation: New jobs are embedded via Queue consumer and stored in Vectorize
5. Matching: Vector search finds similar jobs, then the AI agent (Vercel AI SDK) performs semantic ranking. The agent runs inside Cloudflare Containers (MatchContainer) to support long-running LLM calls.
6. Notifications: Users are notified via Telegram and/or email when matching jobs are found
7. Email Verification: Users can set their email via /email command, receive a verification link, and opt into email notifications

npm run dev              # Start wrangler dev server
npm run dev:cron         # Dev server with test-scheduled flag
npm run deploy           # Deploy to Cloudflare Workers
npm run test             # Run vitest tests
npm run typecheck        # TypeScript type check

1. Create a new crawler file in src/lib/crawler/
2. Export the fetch function
3. Add it to the crawl pipeline in src/jobs/crawl.ts

1. Add the provider client in src/lib/llm/
2. Add environment variables to src/lib/types.ts Env interface
3. Add the API call to the appropriate job handler

1. Add handler in src/bot/handlers/
2. Register in src/bot/bot.ts with bot.command()
3. Add reply text to src/bot/constants.ts

npx vitest run            # Run all tests
npx vitest run --reporter=verbose  # Verbose output

# Type checking
npm run typecheck

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

This project is licensed under the MIT License - see the LICENSE file for details.

• Cloudflare Workers - Serverless compute platform
• Hono - Lightweight web framework
• grammY - Telegram bot framework
• OpenRouter - Unified LLM API gateway
• DeepSeek - LLM provider
• RemoteOK - Remote job board
• WeWorkRemotely - Remote job board

If you have any questions or issues, please:

1. Check the Issues page
2. Create a new issue if needed

⭐ If this project helps you, please give it a star!