Home

Lodestar is a local-first job-search workbench designed to manage the end-to-end lifecycle of job hunting through a structured, automated pipeline. It operates directly over a local Obsidian vault, treating plain-text Markdown files with YAML frontmatter as the primary source of truth for all entities (companies, jobs, and user profiles).

The system combines a high-performance Rust backend with a modern web frontend to provide deep automation—including web scraping, LLM-driven role analysis, and automated fit scoring—while maintaining the portability and longevity of local text files.

Architecture

Lodestar is built using Tauri v2, bridging a native Rust core with a SvelteKit frontend.

The Stack

• Backend (Rust): Handles file system I/O, the durable task queue (SQLite), LLM orchestration, and the job-fetch pipeline
• Frontend (Svelte 5): Utilizes Runes for reactive state management and provides a multi-surface workspace for triaging roles and managing applications
• Persistence: All domain data is stored in a user-selected Obsidian vault. The app also maintains a local data directory for its internal SQLite task queue

System Relationship Diagram

This diagram illustrates how the frontend UI communicates with the Rust core to interact with the external environment and the local vault.

System Bridge: UI to Code Entities

flowchart TD
    subgraph subGraph3 ["Local Filesystem"]
        H["Obsidian Vault (*.md files)"]
        I["App Data (queue.db)"]
    end
    subgraph subGraph2 ["Backend (Rust Core)"]
        D["Note I/O (mod note)"]
        E["Pipeline Worker (mod worker)"]
        F["Task Queue (SqliteQueue)"]
        G["Watcher (mod watcher)"]
    end
    subgraph subGraph1 ["Tauri IPC Bridge"]
        C["Invoke Handlers (tauri::generate_handler!)"]
    end
    subgraph subGraph0 ["Frontend (SvelteKit + Runes)"]
        A["UI Surfaces (Companies, Jobs, Checks)"]
        B["Svelte Stores (companiesStore, checksStore)"]
    end
    A <--> B
    B --> C
    C --> D
    C --> E
    E --> F
    F --> I
    D <--> H
    G --> H
    G --> B

Loading

Major Subsystems

1. Vault I/O & Note Primitives

The system treats Markdown files as structured objects. The note module is responsible for splitting files into YAML frontmatter and Markdown content, enabling round-trip writes that preserve user formatting while updating specific data fields.

• For details, see Note Primitives & Vault I/O.

2. The Job-Fetch Pipeline

A multi-stage automated engine that moves through discovery, detail extraction, and scoring. It uses ScrapingBee for resilient web scraping and OpenRouter for LLM-based analysis.

• Discovery: Scrapes career pages and structures listings.
• Detailing: Fetches full JDs and detects research gaps (e.g., missing salary or tech stack).
• Scoring: Compares job requirements against the user's TargetCriteria and Experience to produce a fit score.
• For details, see Job-Fetch Pipeline.

3. Fit Scoring Engine

A specialized Rust module (fit.rs) that calculates alignment across five dimensions: Seniority, Skills, Compensation, Arrangement, and Domain. It uses a "dealbreaker" logic where failure in a hard filter collapses the total score to zero.

• For details, see Fit Scoring Engine.

4. Product Surfaces

The UI is organized into several functional "surfaces" accessed via a rail navigation system.

Surface	Status	Purpose
Companies	Built	High-level view of targets, screening status, and active roles.
Checks	Built	Telemetry log for the pipeline; tracks LLM costs and scraping success.
Settings	Built	Configuration for API keys and vault pathing.
Triage	Planned	Focused, one-by-one review of new roles.
Pipeline	Planned	Kanban-style board for active applications.

• For details, see Product Surfaces & Navigation.

Core Data Flow

The following diagram maps the lifecycle of data from an external URL to a structured note in the local vault.

Data Flow: External URL to Code Entity

flowchart LR
    subgraph Persistence
        MD["Markdown + YAML"]
    end
    subgraph subGraph1 ["Pipeline (Rust Entities)"]
        SB["ScrapingBeeScraper"]
        OR["OpenRouterLlm"]
        JS["Job Struct"]
    end
    subgraph External
        URL["Job URL"]
    end
    URL --> SB
    SB --> OR
    OR --> JS
    JS --> MD

Loading

Next Steps

• To set up your environment and API keys, see Getting Started & Configuration.
• To understand how to navigate the workspace, see Product Surfaces & Navigation.
• For a deep dive into the data structures, see The Vault: Data Model & Persistence.