Skip to content

The Vault: Data Model & Persistence

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

Relevant source files

Lodestar utilizes a vault-based persistence model, where the filesystem serves as the primary database. Every entity—Companies, Jobs, Domains, and Checks—is stored as a Markdown file within a structured directory tree. This approach ensures that the data remains human-readable, editable via external tools like Obsidian, and version-control friendly.

The system bridges the gap between unstructured Markdown and structured Rust types by using YAML frontmatter for metadata and a dedicated I/O layer that handles round-trip writes while preserving user-authored content.

System Overview: Natural Language to Code Entities

The following diagram illustrates how the conceptual entities in the "Natural Language Space" (the user's mental model) map to specific code entities and their physical storage locations in the "Code Entity Space."

Entity Mapping Diagram

flowchart LR
    M["note.rs: write_note()"]
    subgraph subGraph2 ["Vault Storage (Markdown + YAML)"]
        I["/companies/{slug}.md"]
        J["/jobs/{slug}.md"]
        K["/domains/{slug}.md"]
        L["/checks/{id}.md"]
    end
    subgraph subGraph1 ["Code Entity Space (src-tauri/src/)"]
        E["company.rs: Company struct"]
        F["job.rs: Job struct"]
        G["domain.rs: Domain struct"]
        H["check.rs: Check struct"]
    end
    subgraph subGraph0 ["Natural Language Space"]
        A["Company"]
        B["Job Posting"]
        C["Industry/Domain"]
        D["Pipeline Log"]
    end
    A --> E
    B --> F
    C --> G
    D --> H
    E --> I
    F --> J
    G --> K
    H --> L
    E -.-> M
    F -.-> M
    H -.-> M
    M --> I
    M --> J
    M --> L
Loading

Sources: src-tauri/src/company.rs#16-35src-tauri/src/job.rs#32-75src-tauri/src/note.rs#25-31

Note Primitives & Vault I/O

The foundation of the persistence layer is the note.rs module. It provides generic primitives for manipulating Markdown files without requiring knowledge of the specific entity types. Key responsibilities include:

  • Frontmatter Splitting: Dividing a file into its YAML metadata block and Markdown body src-tauri/src/note.rs#56-65
  • Atomic Field Updates: Replacing specific YAML keys while preserving the rest of the file's byte-for-byte structure src-tauri/src/note.rs#69-84
  • Self-Write Tracking: A mechanism to prevent the file watcher from triggering a reload when the app itself modifies a file src-tauri/src/note.rs#15-31

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

Company Entity

The Company entity represents an organization being tracked. It includes metadata like industry, remote_policy, and status (e.g., "active", "exhausted"). Companies are the root of the discovery pipeline; the system uses the last_checked field to determine if a company is due_for_checksrc-tauri/src/company.rs#77-88

For details, see Company Entity.

Job Entity

The Job entity captures the full lifecycle of a role, from discovery to application. It stores complex data including comp_range, tech_stack, and AI-generated fit_scoressrc-tauri/src/job.rs#32-75 The system supports "lenient parsing," allowing it to recover from malformed YAML fields without losing the entire note src-tauri/src/job.rs#118-134

For details, see Job Entity.

Domain, Metro & Competency Entities

These are supporting reference entities used for categorization and scoring:

  • Domain: Functional tags (e.g., "Fintech") with alias support src-tauri/src/domain.rs#10-20
  • Metro: Geographic regions for filtering.
  • Competency: Definitions of skills used in the fit-scoring rubric.

For details, see Domain, Metro & Competency Entities.

Data Flow: Persistence & UI Synchronization

The following diagram demonstrates how a data change flows from a UI action, through the Rust backend, into the Vault, and back to the UI via the file watcher.

Persistence Data Flow

Sources: src-tauri/src/note.rs#25-31src-tauri/src/note.rs#36-44src-tauri/src/company.rs#253-268src-tauri/src/lib.rs#43-67

Summary Table of Vault Entities

Entity Path Key Metadata (YAML) Primary Body Content
Company /companies/*.md status, domain, careers_url General research notes
Job /jobs/*.md role, comp, fit_score, status Job description & analysis
Domain /domains/*.md aliases, description Industry context
Check /checks/*.md start_time, total_cost, outcome Step-by-step pipeline logs

Sources: src-tauri/src/company.rs#16-35src-tauri/src/job.rs#32-75src-tauri/src/domain.rs#10-20src-tauri/src/check.rs#20-35

Clone this wiki locally