Product Surface & Navigation

Lodestar is structured as a Single Page Application (SPA) hosted within a Tauri v2 shell. The interface is organized around a persistent navigation rail and a dynamic content area driven by SvelteKit routing. The application state and UI are fundamentally driven by the vaultPath, which determines the data context for all surfaces

Root Layout & Navigation Rail

The application's root layout is defined in +layout.svelte, which implements a two-column grid: a fixed-width navigation rail (.rail) and a flexible content area (.app__content)

Navigation Rail

The rail serves as the primary navigation hub, categorizing surfaces into functional areas and diagnostic tools

• Brand: Displays "Lodestar" using the display font
• Active Links: Current routes are highlighted using the .on class, which inverts the rail's color scheme
• Future Surfaces: Placeholders for planned features (Today, Triage, Pipeline, Network, Patterns) are styled with the .future class to indicate they are currently non-functional
• Diagnostics: A secondary section containing the Checks and Settings surfaces

Navigation Logic

Route detection is handled via SvelteKit's page store, which drives the active state of navigation links

Surface	Path Pattern	Code Entity / Route
Companies	/ or /companies/*	src/routes/+page.svelte
Checks	/checks/*	src/routes/checks/ (Planned)
Settings	/settings/*	src/routes/settings/ (Planned)

The Vault-Driven Architecture

The entire UI lifecycle is tied to the selection and monitoring of a local Obsidian vault.

Vault Initialization

When the app starts or a vault is changed, the +layout.svelte component triggers a global synchronization effect. This calls startVaultSync(path), which establishes a bridge between the Rust file watcher and the Svelte stores.

Data Flow & Store Loading

Individual surfaces are responsible for ensuring their respective stores are populated based on the companiesStore.vaultPath.

• Companies Surface: On mount, it checks if companiesStore and domainsStore have been loaded for the current path
• Reactivity: Stores use Svelte 5 runes ($state, $derived) to provide reactive access to vault data

UI State Machine: Vault Path

The following diagram illustrates how the vaultPath flows from the backend through the frontend stores to drive the UI surfaces.

Diagram: Vault Data Flow

flowchart TD
    subgraph subGraph2 ["UI Surfaces"]
        H["Companies (+page.svelte)"]
        I["Checks Surface"]
    end
    subgraph subGraph1 ["Frontend Stores (Svelte 5)"]
        D["vaultSync.ts"]
        E["companiesStore"]
        F["domainsStore"]
        G["checksStore"]
    end
    subgraph subGraph0 ["Backend (Rust)"]
        A["Config/Keychain"]
        B["Tauri Commands"]
        C["Watcher (watcher.rs)"]
    end
    A --> B
    C --> B
    B --> D
    D --> E
    D --> F
    D --> G
    E --> H
    F --> H
    G --> I

Loading

Surface: Companies (The Main Workspace)

The Companies surface (/) is the primary interface for managing the job search pipeline. It features a complex filtering and search system.

Search and Keyboard Navigation

The search input supports advanced keyboard interactions for rapid navigation:

• ArrowUp/Down: Move activeIndex through the view.ranked list
• Enter: Opens the currently selected company slug
• Escape: Clears the query and resets focus

View Filtering (applyView)

The UI state (filters, sort, query) is passed to applyView, which computes the visible subset of companies

• Tabs: Users can toggle between Queue, All, By domain, and Best prospects
• Comboboxes: Multi-select filters for Status, Domain, Remote, Size, and Stage

Diagram: Search & Filter Logic

flowchart LR
    subgraph subGraph2 ["Output Components"]
        L["List Rendering"]
        K["Keyboard Nav"]
        D["Domain Grouping"]
    end
    subgraph Computation
        CS["companiesStore.companies"]
        AV["applyView()"]
        V["view ($derived)"]
    end
    subgraph subGraph0 ["Input State"]
        Q["query ($state)"]
        F["filters ($state)"]
        S["sortKey ($state)"]
    end
    CS --> AV
    Q --> AV
    F --> AV
    S --> AV
    AV --> V
    V --> L
    V --> K
    V --> D

Loading

Surface: Checks (Diagnostics)

The Checks surface provides visibility into the background job-fetch pipeline. It tracks execution history, costs, and telemetry.

• Implementation: Driven by checksStore
• Data Model: Loads CheckSummary objects which aggregate costs (credits and USD) and execution status
• Navigation: Accessed via /checks in the rail

Planned Surfaces

The application includes placeholders for several specialized surfaces intended to complete the job search lifecycle:

1. Today: A daily dashboard for scheduled tasks and follow-ups
2. Triage: High-speed interface for processing new job listings
3. Pipeline: Visual Kanban or list view of active applications
4. Network: CRM for managing professional contacts and referrals
5. Patterns: Analytics on market trends and personal performance