# nichwch/nomad-hypertext architecture

> Architecture diagram of the GitHub repository nichwch/nomad-hypertext, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nichwch/nomad-hypertext
- Repository: https://github.com/nichwch/nomad-hypertext

## Overview

##### Project Type and Purpose
- This is a full-stack application targeted at desktop (MacOS) users that combines a rich, interactive writing interface with built-in semantic search.
- The overall goal is to let users write freely while automatically indexing their content using embeddings and then linking related text pieces.

##### File Structure
- At the top level, you have configuration files and scripts (e.g., package.json, vite.config.js, svelte.config.js, tailwind.config.js) that set up a Svelte-based UI (using .svelte components) and the overall build environment.
- Files like appDB.cjs, appEmbeddings.cjs, db.mjs, and embedding.mjs indicate discrete modules responsible for local storage (vector database) and the AI embedding generation.
- The presence of “parsePDF.mjs” and “query.mjs” suggests additional processing capabilities (e.g., importing PDFs, executing search queries).
- Directory structure within “src” shows routes and components typical of a SvelteKit application: components (Overlay.svelte, SearchModal.svelte, etc.), organized routes (including special routes for notes, settings, and help), and reusable libraries in src/lib.

##### Breakdown of Main Components in the System
a. User Interface (UI) Layer:
- Built on Svelte with routes and UI components found under “src” (e.g., +page.svelte files, Overlay.svelte, SearchResultDisplay.svelte).
- This includes components for the writing interface, search modals, overlay displays, context menus, and settings.
b. Semantic Search Engine:
- OramaSearch is at the core for performing the semantic search on locally stored vectors.
- The UI components interact with this through an API layer (code in modules like query.mjs or components that trigger search events).
c. Embedding Generation Module:
- Modules such as embedding.mjs and appEmbeddings.cjs wrap the functionality for generating vector embeddings from text using Supabase’s gte-small model.
d. Local Vector Database:
- Modules such as appDB.cjs and db.mjs suggest a dedicated mechanism to store the indexed content and embeddings in a local, file-based or in-memory structure.
e. Auxiliary Tools:
- Scripts like parsePDF.mjs and importFromDirectory.mjs may serve to ingest and format external data (e.g., PDF content) into the system.
- There are also components for handling prompts (src/prompt folder) and tooltips (src/lib/tooltip.js) that add to the feature set.

##### Relationships & Data Flows
- The user writes in the UI, which is immediately captured by the front-end components.
- These inputs pass to modules that process the text: a parser (possibly parsePDF.mjs for file imports or direct text inputs) and then to the embedding generator (embedding.mjs/appEmbeddings.cjs) which produces vector representations.
- The vectors are saved into the local database (appDB.cjs/db.mjs) and indexed by OramaSearch.
- When the user queries or interacts with the content (for example, clicking on a paragraph), the UI component triggers a search query (query.mjs) against OramaSearch.
- Search results come back and are rendered by components such as SearchResultDisplay.svelte.

##### Architectural Patterns and Design Principles
- A clear separation of concerns is evident: the SvelteKit frontend handles presentation and routing, while separate modules handle backend logic related to embedding generation and data storage.
- The file-based routing in Svelte guides the UI organization, while Node.js modules (using .mjs and .cjs) encapsulate business logic.
- The application processes data in-memory and on-device, which emphasizes efficiency and offline capability.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "UI Layer"
        UI_WI("Writing Interface\n(src/routes)"):::ui
        UI_SM("Search Modal & Results\n(Overlay.svelte, SearchModal.svelte, SearchResultDisplay.svelte)"):::ui
        UI_PROMPTS("Prompts\n(src/prompt)"):::ui
        UI_TOOLTIP("Tooltips\n(src/lib/tooltip.js)"):::ui
    end

    subgraph "Processing Layer"
        subgraph "Embedding Generation Module"
            EMB1("embedding.mjs"):::proc
            EMB2("appEmbeddings.cjs"):::proc
            EMB1 --- EMB2
        end
        SEM("Semantic Search Engine\n(query.mjs)"):::proc
        AUX1("PDF Parser\n(parsePDF.mjs)"):::proc
        AUX2("Directory Import\n(importFromDirectory.mjs)"):::proc
    end

    subgraph "Data Storage Layer"
        DB1("appDB.cjs"):::db
        DB2("db.mjs"):::db
        DB1 --- DB2
    end

    %% Data Flows
    UI_WI -->|"sendsText"| EMB1
    UI_WI -->|"sendsFile"| AUX1
    UI_WI -->|"sendsFile"| AUX2
    EMB1 -->|"embeds"| DB1
    AUX1 -->|"parses"| DB1
    AUX2 -->|"imports"| DB1
    UI_SM -->|"querys"| SEM
    SEM -->|"searches"| DB1
    DB1 -->|"results"| SEM
    SEM -->|"returns"| UI_SM

    %% Click Events
    click UI_WI "https://github.com/nichwch/nomad-hypertext/tree/main/src/routes"
    click UI_SM "https://github.com/nichwch/nomad-hypertext/tree/main/src/routes"
    click UI_PROMPTS "https://github.com/nichwch/nomad-hypertext/tree/main/src/prompt"
    click UI_TOOLTIP "https://github.com/nichwch/nomad-hypertext/blob/main/src/lib/tooltip.js"
    click EMB1 "https://github.com/nichwch/nomad-hypertext/blob/main/embedding.mjs"
    click EMB2 "https://github.com/nichwch/nomad-hypertext/blob/main/appEmbeddings.cjs"
    click SEM "https://github.com/nichwch/nomad-hypertext/blob/main/query.mjs"
    click DB1 "https://github.com/nichwch/nomad-hypertext/blob/main/appDB.cjs"
    click DB2 "https://github.com/nichwch/nomad-hypertext/blob/main/db.mjs"
    click AUX1 "https://github.com/nichwch/nomad-hypertext/blob/main/parsePDF.mjs"
    click AUX2 "https://github.com/nichwch/nomad-hypertext/blob/main/importFromDirectory.mjs"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef proc fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef db fill:#F4A460,stroke:#000,stroke-width:2px;
```
