Job Agent

Job Agent is an AI-powered job application engine. The product will eventually help users manage resumes, discover software engineering jobs, review normalized listings, approve applications, reuse application answers, and track application status.

Current Status

Current status: Phase 4 Search Experience is complete and certified. Phase 5 Application Queue has not started and requires explicit approval.

Implemented so far:

• Knowledge Base, Resume Management, certified Search Experience, Job Browser, Job Details, and in-memory Search Sessions in apps/web.
• FastAPI knowledge base and resume management APIs in services/api.
• Canonical TypeScript contracts in contracts/domain.
• Provider-independent search orchestration and plugin framework in packages/domain.
• Search result aggregation, normalization, validation, deduplication, quality filtering, ranking, unified response processing, and certified end-to-end search execution in packages/domain.
• Greenhouse, Lever, and Ashby raw search connectors in packages/providers.
• Shared workspace package in packages/shared.
• Linting, formatting, type checking, tests, build, Docker Compose config, CI, and VS Code support.

Implemented product scope is intentionally limited to resume management, knowledge base CRUD, certified search execution and browsing, in-memory search sessions, client-side job selection, and reviewed read-only job inspection. Persistence, automation, AI, application queues, tracking, and application workflows remain out of scope.

Quick Start

Prerequisites:

• Node.js 24
• pnpm 11
• Python 3.13
• uv
• Docker Desktop, optional for container verification

Bootstrap the repo:

pnpm bootstrap

Run both development servers:

pnpm dev

Run with deterministic Search smoke-test results:

pnpm dev:smoke

Run the full health check:

pnpm verify

Run with Docker after Docker Desktop is running:

docker compose up --build

Common Commands

Command	Purpose
pnpm bootstrap	Install JavaScript and Python dependencies.
pnpm dev	Run frontend and backend together.
pnpm dev:smoke	Run dev servers with the local deterministic search provider.
pnpm dev:web	Run only the Next.js app.
pnpm dev:api	Run only the FastAPI service.
pnpm verify	Format check, lint, typecheck, test, and build.
pnpm lint	Run TypeScript and Python linting.
pnpm typecheck	Run TypeScript and Python type checks.
pnpm test	Run all tests.
pnpm build	Build TypeScript packages, web app, and Python compile check.
pnpm clean	Remove generated local build/cache outputs.

Repository Structure

• apps/web: Next.js dashboard for knowledge base, resume management, search execution, Search Sessions, Job Browser, and Job Details.
• services/api: FastAPI backend with health, version, resume, and knowledge endpoints.
• contracts/domain: canonical @job-agent/contracts package.
• packages/domain: provider-independent search orchestration and plugin framework.
• docs/search: search result processing pipeline documentation.
• packages/providers: provider connector infrastructure and raw Greenhouse/Lever/Ashby connectors.
• packages/shared: small shared TypeScript package.
• docs: supporting docs and phase reports.
• scripts: local developer automation.
• specs: future feature specifications.
• playbooks: repeatable engineering procedures.

More Docs

• API Reference
• Getting Started
• Contributing
• Engineering Guide
• Project Plan
• Current State
• MVP Status
• Search Engine Release Audit
• Phase 4.1 Report
• Phase 4.1 Review Report
• Phase 4.2 Report
• Phase 4.2 Review Report
• Phase 4.3 Report
• Phase 4.3 Review Report
• Phase 4.4 Report
• Phase 4.4 Review Report
• Phase 4.5 Certification Report
• Phase 4 Smoke Test Report
• Local QA Reset and Seed
• Browser Smoke Test