# perone/vectorvfs architecture

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

- Interactive diagram: https://gitdiagram.com/perone/vectorvfs
- Repository: https://github.com/perone/vectorvfs

## Overview

##### Project Type and Purpose
- This is an open-source Python tool/library (not a full-stack web app) that:
- Exposes a CLI for the user
- Embeds files in a local Linux filesystem by writing vector embeddings into file xattrs
- Offers a library API for embedding, storing, and searching

##### Main Components
From the file tree and README, the core components are:
a. User Interface
– vectorvfs/cli.py
– Exposes commands (index, search, etc.)
b. Core Library
– vectorvfs/vfsstore.py
- Traverses directories, reads/writes xattrs
– vectorvfs/encoders.py
- Wraps embedding models (Meta Perception Encoders)
– vectorvfs/utils.py
- File utilities, xattr helpers
c. External Dependencies
– Embedding models (in-process Python, may call PyTorch or HF transformers)
– Linux VFS extended attributes subsystem
d. Test Suite
– tests/… (validates encoders, VFSStore behavior)

##### Relationships and Data Flow
- CLI → Core Library API
- The user invokes `vectorvfs index …` or `vectorvfs search …`.
- Core Library ↔ Linux VFS
- vfsstore traverses folder tree → reads/writes xattrs on each file.
- Core Library → Embedding Model
- encoders.encode(file_content) → produces vector of floats.
- Core Library → Search Engine (in-memory similarity search)
- Computes nearest neighbors over stored embeddings.

##### Architectural Patterns & Design Principles
- Modular library design: clear separation between CLI, storage layer, encoder layer.
- Pluggable encoder interface: users can swap in custom embedding functions.
- Zero-overhead indexing: no external DB—leverages VFS xattrs directly.
- Single-process, no background daemons (lightweight, portable).

##### Essential Elements to Capture
- Component names exactly as in code (cli.py, vfsstore.py, encoders.py)
- Data flows: user input → encoding → xattr storage → retrieval
- External interfaces: OS xattrs, embedding model library
- Extensibility: custom encoder hook

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors and External Systems
    User(("User")):::external
    LinuxVFS(("Linux VFS\n(xattrs)")):::external
    Embedding(("Embedding Model\n(PyTorch/HF)")):::external
    Doc["architecture.rst"]:::external

    %% User Interface
    subgraph "User Interface"
        CLI["cli.py"]:::cli
    end

    %% Core Library Modules
    subgraph "Core Library"
        VFSStore["vfsstore.py"]:::core
        Encoders["encoders.py"]:::core
        Utils["utils.py"]:::core
    end

    %% In-Memory Search Component
    subgraph "In-Memory Search"
        Search["Similarity Engine"]:::core
    end

    %% Test Suite
    subgraph "Test Suite"
        TE["test_encoders.py"]:::test
        TV["test_vfsstore.py"]:::test
    end

    %% Data Flows
    User -->|"runs CLI command"| CLI
    CLI -->|"calls API"| VFSStore
    VFSStore -->|"encode()"| Encoders
    VFSStore -->|"write/read xattr"| LinuxVFS
    VFSStore -->|"search()/store embeddings"| Search
    Encoders -->|"uses"| Embedding
    TE -->|"validates"| Encoders
    TV -->|"validates"| VFSStore

    %% Click Events
    click CLI "https://github.com/perone/vectorvfs/blob/main/vectorvfs/cli.py"
    click VFSStore "https://github.com/perone/vectorvfs/blob/main/vectorvfs/vfsstore.py"
    click Encoders "https://github.com/perone/vectorvfs/blob/main/vectorvfs/encoders.py"
    click Utils "https://github.com/perone/vectorvfs/blob/main/vectorvfs/utils.py"
    click TE "https://github.com/perone/vectorvfs/blob/main/tests/test_encoders.py"
    click TV "https://github.com/perone/vectorvfs/blob/main/tests/test_vfsstore.py"
    click Doc "https://github.com/perone/vectorvfs/blob/main/docs/source/architecture.rst"

    %% Styling
    classDef cli fill:#cce5ff,stroke:#004085,color:#004085;
    classDef core fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-dasharray: 5 5;
    classDef test fill:#fff3cd,stroke:#856404,color:#856404;
```
