Getting Started & Configuration

Lodestar is a desktop application built on Tauri v2 and Svelte 5, designed to operate directly over a local Obsidian vault. Setting up the development environment involves configuring the Rust and Node.js toolchains, wiring the application to a local directory (the "vault"), and securely provisioning API keys for the job-fetch pipeline.

Development Environment Setup

The project requires both the Rust toolchain (for the Tauri core) and the Node.js ecosystem (for the SvelteKit frontend).

1. Rust: Install via rustup. The project uses the 2021 edition
2. Node.js: Install via nvm or your preferred manager.
3. Dependencies:

• Install frontend dependencies: npm install.
• The Rust backend utilizes tauri-plugin-opener and tauri-plugin-dialog

4. Running the App:

• Development mode: npm run tauri dev. This starts the Vite dev server for the frontend and compiles the Rust binary.

Key Build Tools

Tool	Purpose	Configuration
Vite	Frontend HMR & Bundling	vite.config.js
Tauri CLI	Rust/Webview bridge & Packaging	package.json#13
Vitest	TypeScript unit testing	package.json#39
Cargo	Rust dependency management	src-tauri/Cargo.toml

---

Vault vs. App Config Directory

Lodestar distinguishes between two storage locations: the Vault Directory (user-owned data) and the App Config Directory (application state and model preferences).

1. The Vault Directory

The Vault is a standard folder (ideally an Obsidian vault) where all entities are stored as Markdown files with YAML frontmatter. The path is selected by the user via a native folder picker

2. The App Config Directory

Stored in the OS-standard application config path (e.g., ~/Library/Application Support/dev.lodestar.lodestar/ on macOS). This directory contains config.json, which governs the LLM pipeline behavior.

Data Flow: Config Management The config.rs module handles the persistence of PipelineConfig. If config.json is missing, the app generates a default version using Claude models

App Config Structure

flowchart TD
    subgraph subGraph1 ["Code Entity Space"]
        LDR["load_config()"]
        SVR["save_config()"]
        TCFG["PipelineConfig (Struct)"]
        MTIERS["ModelTiers (Struct)"]
    end
    subgraph subGraph0 ["App Config Directory"]
        CFG["config.json"]
    end
    CFG --> LDR
    LDR --> TCFG
    TCFG --> MTIERS
    SVR --> CFG

Loading

---

Secret Management (API Keys)

Lodestar requires API keys for ScrapingBee (web scraping) and OpenRouter (LLM inference). To maintain security, these keys are never stored in the vault and never written to disk in plaintext. Instead, they are stored in the OS Keychain via the keyring crate

Security Implementation

• Whitelisting: Only scrapingbee_api_key and openrouter_api_key are permitted
• Write-Only Frontend: The Svelte UI can set keys but cannot read them back
• Auth Prompt Mitigation: On macOS, Lodestar uses SecItemCopyMatching for presence checks to avoid triggering repeated OS password prompts
• In-Memory Caching: Keys are cached in a OnceLock<Mutex<HashMap>> after the first retrieval to minimize keychain hits

Secret Access Data Flow

sequenceDiagram
    participant UI as "Settings Surface (+page.svelte)"
    participant CMD as "tauri::command (set_secret)"
    participant SEC as "secrets.rs"
    participant KC as "OS Keychain (Apple-Native)"
    UI->>CMD: invoke("set_secret" | {key | value})
    CMD->>SEC: set_secret_value(key | value)
    SEC->>KC: keyring::Entry.set_password(value)
    SEC->>SEC: Update in-memory CACHE
    UI->>CMD: invoke("secret_present" | {key})
    CMD->>SEC: is_present(key)
    SEC->>KC: SecItemCopyMatching (existence check)
    KC-->>UI: Returns boolean (present/absent)

Loading

---

Model Tiers & LLM Configuration

The application classifies every LLM pipeline stage into a Tier. Users can map these tiers to specific model slugs (OpenRouter) in the Settings/Config.

Tier	Default Model	Purpose
Frontier	anthropic/claude-opus-4.8	Nuanced reasoning (JD analysis, alignment)
Balanced	anthropic/claude-sonnet-4.6	High-volume extraction (Listing structuring)
Speed	anthropic/claude-haiku-4.5	Fast, low-cost utility tasks

Implementation Detail

The function tier_for_stage in config.rs maps internal stage names to these tiers. For example, structure-listings is mapped to Tier::Balanced to save costs, while alignment defaults to Tier::Frontier

---

Initial Vault Wiring

When the app starts, the user must select a vault. This wiring is driven by the frontend and communicated to the backend to initialize file watchers.

1. Picker: pickVault() calls the Tauri native dialog
2. Validation: The app verifies the directory structure.
3. Markdown Processing: Lodestar uses marked for parsing and dompurify for sanitization to ensure that LLM-generated or scraped content is safe to render in the webview

Markdown Sanitization Flow

flowchart LR
    HTML["Sanitized HTML (Safe for @html)"]
    subgraph subGraph1 ["Code Entity Space"]
        M["marked.parse()"]
        P["DOMPurify.sanitize()"]
        R["renderMarkdown()"]
    end
    subgraph subGraph0 ["Natural Language Space"]
        RAW["Raw Markdown (from Vault/LLM)"]
    end
    RAW --> R
    R --> M
    M --> P
    P --> HTML

Loading