# bbawj/obsidian-semantic-search architecture

> Architecture diagram of the GitHub repository bbawj/obsidian-semantic-search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bbawj/obsidian-semantic-search
- Repository: https://github.com/bbawj/obsidian-semantic-search

## Overview

##### Project Type & Purpose
- Type: A full-stack Obsidian plugin combining a TypeScript “frontend” (Obsidian UI integration) with a Rust/WASM “core” (text processing, CSV generation, embedding).
- Purpose: Let Obsidian users generate semantic-searchable embeddings of their notes and query via a modal or inline link suggestions.

##### File Structure
- Top level:
- main.ts + manifest.json → entry point & Obsidian plugin definition
- esbuild.config.mjs, tsconfig.json → build pipeline for TypeScript
- release.sh, version-bump.mjs → CI/release scripts
- Cargo.toml, wasm-pack integration via esbuild → Rust/WASM module
- src/ (Rust)
- embedding.rs, file_processor.rs, generate_input.rs, obsidian.rs, error.rs → core text processing & API calls
- settings/ → Rust types for plugin settings
- src/ui (TypeScript)
- generateEmbeddingsModal.ts, queryModal.ts → UI command entrypoints
- linkSuggest.ts, suggestion.ts → context menu + suggestion component
- types/obsidian → type definitions for Obsidian APIs
- assets: styles.css

##### Extract Key Technical Insights from README
- Commands: Generate Input → input.csv; Generate Embedding → embedding.csv via external API; Open Query Modal → semantic search UI; Link suggestion using `{{}}`.
- Configurable via Obsidian “data.json” (API URL, key, model, regex, etc.)
- Dependencies: Obsidian plugin API, TypeScript, Rust/WASM, external embedding API (OpenAI, Ollama, etc.)

##### Main Components & Interactions
a. Components:
1. Obsidian Host – Provides plugin lifecycle, UI modals, vault FS access
2. Plugin Frontend (TypeScript) – main.ts + UI modules
3. WASM Core (Rust) – text-to-CSV, batching logic, fetching embeddings (or providing data to TS for fetch)
4. External Embedding Service – HTTP API (e.g. OpenAI)
5. File System (Vault) – input.csv, embedding.csv, plugin settings

b. Data Flow & Relationships:
1. User triggers “Generate Input” → Frontend calls WASM generate_input → WASM processes markdown, writes input.csv to vault
2. User triggers “Generate Embedding” → Frontend reads input.csv, calls WASM/embed or TS wraps fetch calls → External API returns embeddings → results written to embedding.csv
3. User triggers “Open Query Modal” or types `{{}}` → Frontend loads embedding.csv, prompts user, computes similarity (in WASM or TS), renders suggestions via UI modules → optionally writes links back to markdown

c. Architectural Patterns & Principles:
- Separation of concerns: UI vs. core logic
- WASM for CPU-intensive tasks and to share logic across platforms
- Clear command-pattern mapping from Obsidian commands → UI modules → core services
- Batch processing for API rate limits

d. Key Technologies/Frameworks:
- Obsidian Plugin API (host)
- TypeScript + esbuild
- wasm-pack, Rust → WebAssembly module
- Fetch/HTTP for embedding API
- CSV I/O via vault FS

##### Final Recommendations
- Be as detailed as possible: include settings flows (where user config lives), error handling path (Rust error.rs), and UI modules for each commands/view.
- Technology stacks next to each component.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interaction
    User["User"]:::ext
    User -->|"triggers command"| Frontend

    %% Runtime Environment
    subgraph "Runtime Environment"
        direction TB

        %% Obsidian Host
        subgraph "Obsidian Host"
            direction TB
            HostManifest["manifest.json"]:::ext
            HostMainTS["main.ts"]:::ext
            ObsidianRs["obsidian.rs"]:::core
            ObsAPITypes["index.d.ts"]:::ext
        end

        %% Plugin Frontend
        subgraph "Plugin Frontend (TypeScript UI)" 
            direction TB
            PFMainTS["main.ts"]:::ui
            GenModal["generateEmbeddingsModal.ts"]:::ui
            QueryModal["queryModal.ts"]:::ui
            LinkSuggest["linkSuggest.ts"]:::ui
            SuggestComp["suggestion.ts"]:::ui
            Styles["styles.css"]:::ui
        end

        %% WASM Core
        subgraph "WASM Core (Rust)"
            direction TB
            Cargo["Cargo.toml"]:::core
            LibRs["lib.rs"]:::core
            EmbeddingRs["embedding.rs"]:::core
            FileProcRs["file_processor.rs"]:::core
            GenInputRs["generate_input.rs"]:::core
            ErrorRs["error.rs"]:::core
            SettingsRs["settings.ts"]:::core
        end

        %% External & Storage
        ExternalAPI["External Embedding API"]:::ext
        VaultFS["Vault FS (input.csv, embedding.csv, data.json)"]:::ext
    end

    %% Build & Release Pipeline
    subgraph "Build & Release Pipeline"
        direction TB
        ESBuild["esbuild.config.mjs"]:::build
        TSConfig["tsconfig.json"]:::build
        ReleaseSH["release.sh"]:::build
        VersionBump["version-bump.mjs"]:::build
    end

    %% Data Flows
    Frontend -->|"calls WASM generate_input"| GenInputRs
    GenInputRs -->|"writes input.csv"| VaultFS

    Frontend -->|"reads input.csv"| VaultFS
    Frontend -->|"requests embeddings"| ExternalAPI
    ExternalAPI -->|"returns embeddings"| Frontend
    Frontend -->|"writes embedding.csv"| VaultFS

    Frontend -->|"opens query modal"| QueryModal
    Frontend -->|"loads embedding.csv"| VaultFS
    Frontend -->|"computes similarity"\nvia WASM Core| EmbeddingRs
    EmbeddingRs -->|"returns results"| Frontend
    Frontend -->|"renders suggestions"| SuggestComp
    Frontend -->|"writes links"| VaultFS

    %% Settings Flow
    VaultFS -->|"reads data.json"| Frontend
    VaultFS -->|"reads data.json"| SettingsRs

    %% Build dependencies
    ESBuild --> TSConfig
    ESBuild --> PFMainTS
    ESBuild --> LibRs
    ReleaseSH --> VersionBump

    %% Click Events - Obsidian Host
    click HostManifest "https://github.com/bbawj/obsidian-semantic-search/blob/main/manifest.json"
    click HostMainTS "https://github.com/bbawj/obsidian-semantic-search/blob/main/main.ts"
    click ObsidianRs "https://github.com/bbawj/obsidian-semantic-search/blob/main/src/obsidian.rs"
    click ObsAPITypes "https://github.com/bbawj/obsidian-semantic-search/blob/main/types/obsidian/index.d.ts"

    %% Click Events - Plugin Frontend
    click PFMainTS "https://github.com/bbawj/obsidian-semantic-search/blob/main/main.ts"
    click GenModal "https://github.com/bbawj/obsidian-semantic-search/blob/main/src/ui/generateEmbeddingsModal.ts"
    click QueryModal "https://github.com/bbawj/obsidian-semantic-search/blob/main/src/ui/queryModal.ts"
    click LinkSuggest "https://github.com/bbawj/obsidian-semantic-search/blob/main/src/ui/linkSuggest.ts"
    click SuggestComp "https://github.com/bbawj/obsidian-semantic-search/blob/main/src/ui/suggestion.ts"
    click Styles "https://github.com/bbawj/obsidian-semantic-search/blob/main/styles.css"

    %% Click Events - WASM Core
    click Cargo "https://github.com/bbawj/obsidian-semantic-search/blob/main/Cargo.toml"
    click LibRs "https://github.com/bbawj/obsidian-semantic-search/blob/main/src/lib.rs"
    click EmbeddingRs "https://github.com/bbawj/obsidian-semantic-search/blob/main/src/embedding.rs"
    click FileProcRs "https://github.com/bbawj/obsidian-semantic-search/blob/main/src/file_processor.rs"
    click GenInputRs "https://github.com/bbawj/obsidian-semantic-search/blob/main/src/generate_input.rs"
    click ErrorRs "https://github.com/bbawj/obsidian-semantic-search/blob/main/src/error.rs"
    click SettingsRs "https://github.com/bbawj/obsidian-semantic-search/blob/main/src/settings/settings.ts"

    %% Click Events - Build Pipeline
    click ESBuild "https://github.com/bbawj/obsidian-semantic-search/blob/main/esbuild.config.mjs"
    click TSConfig "https://github.com/bbawj/obsidian-semantic-search/blob/main/tsconfig.json"
    click ReleaseSH "https://github.com/bbawj/obsidian-semantic-search/blob/main/release.sh"
    click VersionBump "https://github.com/bbawj/obsidian-semantic-search/blob/main/version-bump.mjs"

    %% Styles
    classDef ui fill:#D6EAF8,stroke:#2980B9
    classDef core fill:#D5F5E3,stroke:#27AE60
    classDef ext fill:#E5E7E9,stroke:#7F8C8D
    classDef build fill:#F9E79F,stroke:#B7950B
```
