Skip to content

Frontend UI

Jump to bottom
Chazona Baum edited this page Jun 24, 2026 · 2 revisions

Relevant source files

The Lodestar frontend is a SvelteKit application running within a Tauri v2 container. It leverages Svelte 5 and its "runes" system ($state, $derived, $effect) for reactive state management. The UI is designed to be a thin, reactive layer over the local Obsidian vault, communicating with the Rust backend via a Tauri IPC bridge.

Architecture & State Management

The frontend architecture centers around global Svelte "stores" that encapsulate both the reactive state and the Tauri invoke calls used to modify that state. These stores ensure that data remains synchronized across different UI surfaces.

Global Stores (Runes-based)

Lodestar uses singleton state objects defined with Svelte 5 runes. These stores handle loading data from the backend and providing helper methods for CRUD operations.

Store File Responsibility
companiesStore src/lib/companies.svelte.ts#28-87 Manages the list of companies, vault path selection, and company-level updates (status, notes, fields).
checksStore src/lib/checks.svelte.ts#7-36 Manages the history of pipeline runs (Checks), including telemetry and cost rollups.
domainsStore src/lib/domains.svelte.ts#7-47 Manages industry/functional domain reference data used for filtering and resolution.

Vault Synchronization

To maintain a "single source of truth" with the filesystem, the frontend implements a live-reload mechanism. When a file is changed externally (e.g., in Obsidian), the Rust backend emits a record:changed event. The startVaultSync function listens for these events and triggers updates in the corresponding stores src/routes/+layout.svelte#20-30

UI-to-Backend Bridge (IPC)

The frontend communicates with Rust using the Tauri invoke API. These calls are typically wrapped in TypeScript service functions that match the backend's expected JSON payloads src/lib/company.ts#44-83

flowchart TD
    subgraph subGraph1 ["Backend (Rust)"]
        Cmd["Tauri Commands"]
        Vault["Markdown Vault"]
        Watcher["File Watcher"]
    end
    subgraph subGraph0 ["Frontend (Svelte 5)"]
        UI["UI Components"]
        Store["companiesStore / checksStore"]
        TS["TypeScript IPC Wrappers (invoke)"]
        VS["vaultSync.ts"]
    end
    UI --> Store
    Store --> TS
    VS --> Store
    Cmd --> Vault
    Watcher --> VS
    TS --> Cmd
Loading

Sources:src/lib/companies.svelte.ts#1-87src/lib/company.ts#1-84src/routes/+layout.svelte#1-38

Main Navigation & Layout

The application uses a "Rail" navigation pattern, providing quick access to the primary product surfaces and diagnostic views.

  • Primary Surfaces: The main workflow revolves around the Companies view, which serves as the root route (/).
  • Diagnostics: Technical views like Checks and Settings are grouped at the bottom of the rail src/routes/+layout.svelte#41-53
  • Future Surfaces: The UI includes placeholders for upcoming features such as "Today", "Triage", and "Pipeline" src/routes/+layout.svelte#43-48

Sources:src/routes/+layout.svelte#32-58

Major UI Surfaces

The Lodestar UI is divided into several specialized surfaces, each documented in detail on its own child page.

Companies Surface

The primary entry point for managing the lead funnel. It features a multi-tab list (Queue, All, By Domain, Best Prospects) and a powerful search/filter interface using the Combobox component.

Company Workspace & Roles Tab

A detailed view of a single company, providing a "workspace" layout for research and role management.

  • Key Logic: Displays the Roles tab with the "Step Strip" visualization of the pipeline's progress for each job.
  • Key Interaction: Inline editing of company notes and metadata src/lib/companies.svelte.ts#69-71

Job Detail Page

Deep dive into a specific job listing, showing the results of the LLM structuring and the fit scoring engine.

  • Key Logic: Displays sub-scores (Seniority, Skills, etc.) and allows for status transitions (Selected, Applied, Skipped).

Checks Surface

A diagnostic surface for monitoring the automated pipeline.

  • Key Logic: Displays a list of CheckSummary objects with cost rollups in credits and USD src/lib/checks.svelte.ts#1-36
  • Key Interaction: Detailed telemetry view showing every step of an LLM or scraping run.

UI Component Library & Styles

The design system is built on a custom set of CSS tokens and reusable components.

  • Styling Strategy: Uses a tiered CSS architecture: tokens -> reset -> elements -> components -> layoutsrc/lib/styles/index.css#1-32
  • Shared Atoms: Buttons, Chips, Monograms, and Modals.

Data Flow & IPC Mapping

The following diagram bridges the TypeScript interfaces used in the UI to the underlying Rust commands and storage entities.

flowchart LR
    subgraph subGraph1 ["Rust (src-tauri/src/)"]
        R_Cmd["mod commands"]
        R_Note["mod note"]
        R_Comp["struct Company"]
    end
    subgraph subGraph0 ["TypeScript (src/lib/company.ts)"]
        T_Comp["interface Company"]
        T_New["interface NewCompany"]
        T_List["listCompanies()"]
        T_Update["updateCompanyField()"]
    end
    T_List --> R_Cmd
    T_Update --> R_Cmd
    R_Cmd --> R_Comp
    R_Comp --> R_Note
    T_Comp --> R_Comp
Loading

Sources:src/lib/company.ts#3-83src/lib/companies.svelte.ts#28-87

Style System

Lodestar uses a global CSS architecture managed via a single entry point: src/lib/styles/index.css. This file imports the entire design system in a specific cascade order to ensure predictable overrides src/lib/styles/index.css#1-32

  1. Tokens: CSS variables for colors, spacing, and typography.
  2. Reset/Elements: Global defaults for HTML tags.
  3. Components: Reusable atoms like .btn, .chip, and .modal.
  4. Layout: Page-specific styles (e.g., workspace.css, roles.css).

Sources:src/lib/styles/index.css#1-32

Clone this wiki locally