Job Compass

The search intelligence layer for China's fragmented job market.

A local-first, explainable job search console for Chinese recruiting platforms, built to find more relevant roles than rigid site filters ever will.

Why This Exists

China's major recruiting websites are powerful data sources, but they are poor search partners.

They tend to over-filter, under-explain, and make adjacent opportunities disappear the moment your query becomes even slightly specific. That is exactly where strong candidates lose visibility into jobs they would actually want.

Job Compass takes the opposite approach:

• wide recall first so good roles are not filtered out too early;
• local semantic reranking so your real preferences matter more than brittle site filters;
• explainable recommendations so every surfaced job has a reason to exist.

This project is designed as a serious personal job-search cockpit, not another thin job-board clone.

What Makes Job Compass Different

1. Fuzzy preferences instead of exact-match traps

You can describe:

• preferred city;
• role family;
• company nature;
• salary expectations;
• longer-form career intent.

The system expands those inputs into broader search intent, then reranks locally using soft constraints instead of acting like every preference is a hard filter.

2. Recommendations that help you discover, not just confirm

Job Compass combines:

• current-query match quality;
• career-profile similarity;
• behavioral signals from saved and clicked jobs;
• adjacent-opportunity exploration.

That means it can surface the jobs you asked for and the jobs you did not know to ask for.

3. Honest architecture for daily use

The project is local-first by design:

• SQLite for durable personal history;
• adapter-based crawler runtime;
• explicit site status and failure isolation;
• explainable ranking output;
• no fake “AI magic” hand-waving.

Current Capabilities

• polished web console for fuzzy search preferences;
• semantic intent expansion for role, location, company type, and salary;
• hybrid ranking engine with explanation badges;
• recommendation pipeline with profile and behavior signals;
• SQLite persistence for jobs, sessions, companies, and interactions;
• adapter runtime for BOSS直聘, 智联招聘, 51job, 猎聘;
• /api/search end-to-end search flow;
• test coverage across domain, db, adapters, api, and UI.

Current Status

This repository is a strong public foundation release, not a finished live crawler product.

What is already real:

• the search model;
• the ranking and recommendation engine;
• the UI;
• the persistence layer;
• the adapter orchestration runtime.

What is still being completed:

• live extraction logic for each major job platform;
• site-specific Playwright flows for listing and detail parsing;
• persistent UI feedback actions wired into historical learning.

Important behavior note:

• the landing page can render a clearly labeled preview state;
• the real /api/search route does not fake live search results when adapters return nothing;
• adapter failures and empty live searches are surfaced honestly.

Product Experience

The intended workflow is simple:

1. Enter a job city, role family, company preference, and salary expectation.
2. Let the system broaden intent instead of narrowing too early.
3. Aggregate candidates from multiple sites.
4. Rank locally with transparent explanations.
5. Save, hide, and refine preferences over time.

The long-term goal is to turn job search from scattered browsing into a controlled research workflow.

Tech Stack

• Framework: Next.js 16 + React 19
• Language: TypeScript
• Styling: Tailwind CSS 4
• Persistence: SQLite via better-sqlite3
• Automation: Playwright-ready adapter runtime
• Validation: Zod
• Testing: Vitest + Testing Library

Repository Structure

src/app                  Next.js pages and API routes
src/features/search      Search UI, domain logic, and server orchestration
src/features/adapters    Multi-site adapter runtime and site registry
src/server/db            SQLite client and repositories
tests                    Domain, UI, API, adapter, and database tests
docs/plans               Product design and implementation plans

Getting Started

npm install
npm run dev

Open http://localhost:3000.

Verification

npm run test
npm run lint
npm run build

Roadmap

• implement real BOSS直聘 and 智联招聘 browser adapters first;
• add persistent Playwright profile bootstrap flows;
• capture live jobs into SQLite and track history over time;
• wire save/hide/feedback actions from UI into ranking signals;
• expand beyond the core four sites with pluggable adapters.

Vision

Job Compass is built around a simple belief:

the best job opportunities are often one layer outside the exact filter you typed.

The product exists to make that layer searchable, rankable, and visible.