vesaias/jobnavigator

1. JobNavigator is a self-hosted, three-part system: a Python backend API, a React/Tailwind frontend, and a Chrome extension for passive LinkedIn/job capture. PostgreSQL is the persistent store, and Docker Compose/Caddy/nginx are used to run and expose the stack locally or self-hosted.

2. The backend is the orchestration center. backend/main.py and the FastAPI routes under backend/api/ expose the domain surface for jobs, companies, searches, resumes, applications, cover letters, persona, and settings. These routes are the main boundary between the UI/extension and the core job automation logic.

3. Job discovery is split across multiple ingestion sources. The scraper subsystem handles career pages via Playwright, plus dedicated ATS adapters in backend/scraper/ats/ for Workday, Greenhouse, Lever, Ashby, Oracle HCM, Phenom, TalentBrew, Rippling, SmartRecruiters, Google, Meta, and generic/custom pages. Separate source adapters cover aggregators and special inputs like JobSpy, Levels.fyi, Jobright, LinkedIn personal collections, and the Chrome extension.

4. Scraping is not just fetching pages; it has a processing pipeline in backend/scraper/_shared/ and backend/scraper/orchestrator.py. Shared concerns include browser control, URL normalization, URL safety, deduplication, and filtering, which turn many heterogeneous sources into one normalized job record model before it reaches the database.

5. After ingestion, the backend enriches and filters jobs. The analyzer layer computes salary extraction, H-1B/company-labor lookup, CV scoring, cover-letter generation, and LLM-backed analysis. This is where job data becomes actionable: matching against resumes/persona, generating reports, and preparing tailored documents.

6. The LLM boundary is abstracted so multiple providers can be swapped without changing the rest of the system. backend/analyzer/llm_client.py plus cost/logging helpers support Anthropic/Claude, OpenAI, Ollama, and OpenAI-compatible providers, while tests indicate prompt caching and call logging are first-class concerns.

7. Resume and cover-letter generation are template-driven. The backend/resume_templates/ and backend/cover_letter_templates/ directories contain multiple auto-discovered themes, each with metadata and Jinja templates. The backend renders these into exportable documents, and the README indicates PDF generation is done through Playwright.

8. Tracking and follow-up are separate async subsystems. backend/email_monitor/ connects to Gmail via OAuth and parses replies to update application state, while backend/notifier/telegram.py sends alerts, daily digests, and scrape-health notifications. backend/job_monitor.py and backend/scheduler.py coordinate periodic jobs such as scraping, email checks, cleanup, and other maintenance tasks.

9. The frontend is a single-page app built with React 18, Vite, Tailwind, and Recharts. Its components map closely to backend domains: job feed, application board, company manager, resume builder, cover-letter builder, persona, search manager, settings, and stats. The frontend consumes the backend API and is responsible for interactive review, filtering, drag-and-drop status changes, and editing content.

10. The Chrome extension is a separate capture surface, not just a UI add-on. Under extension/, the content script and background service worker support passive LinkedIn capture and “send job from any page” behavior, giving the system a browser-side ingestion path that bypasses the normal scraper when needed.

11. The data model is centered on jobs, companies, searches, resumes, applications, and personas, with status transitions and scoring artifacts persisted in PostgreSQL. The tests show important behaviors like deduplication, caching, best-score selection, job-run targeting, company alias filtering, and transition history, which suggests the app treats these as durable workflow entities rather than ephemeral search results.

12. External service boundaries matter to the architecture: job boards/ATS pages, MyVisaJobs for H-1B data, Gmail for inbox monitoring, Telegram for notifications, and LLM providers for scoring/tailoring. The system is designed so each of these can fail independently without collapsing the core app, which is why scraping, AI, tracking, and messaging are separated into distinct backend modules.