# not-pizza/victor architecture

> Architecture diagram of the GitHub repository not-pizza/victor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/not-pizza/victor
- Repository: https://github.com/not-pizza/victor

## Overview

##### Main Components

a) Core Components:
- Vector Storage Engine (centered around packed_vector.rs)
- Database Interface Layer (db.rs)
- Filesystem Abstractions (filesystem module)
- Native Filesystem Implementation
- In-Memory Implementation
- Web Filesystem Implementation (OPFS)
- Vector Processing Components
- Similarity Calculator (similarity.rs)
- Decomposition Engine (PCA) (decomposition.rs)

b) External Interfaces:
- Rust API
- Web/WASM API
- Optional FastEmbed Integration

##### Application Layer (Top)
- Rust API Interface
- Web/WASM Interface
##### Core Layer (Middle)
- Database Operations
- Vector Processing
##### Storage Layer (Bottom)
- Filesystem Implementations
- Packed Vector Storage

##### Key Relationships to Highlight

- Data flow for vector storage and retrieval
- API communication paths
- Storage backend selection paths
- Vector compression flows

##### Specific Implementation Details

a) Packed Vector Storage Format
- Efficient 1.5KB representation vs 20.6KB JSON
- Compression ratios
b) File System Abstraction
- How the three implementations (native, memory, web) share interfaces

##### Performance Characteristics

Annotations for:
- Vector storage efficiency
- Compression ratios
- Search performance metrics

Key Technical Details to Emphasize:
- The 1536-dimension vector optimization
- The three distinct filesystem implementations
- The WASM compilation target
- The tag-based filtering system
- PCA compression capability

This architecture should emphasize Victor's unique selling points: its storage efficiency, web optimization, and flexible deployment options, while maintaining technical accuracy in representing the internal components and their interactions.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef api fill:#FFE873,stroke:#333
    classDef core fill:#4B8BBE,stroke:#333,color:white
    classDef storage fill:#4B8BBE,stroke:#333,color:white
    classDef filesystem fill:#50C878,stroke:#333
    classDef web fill:#FFB6C1,stroke:#333
    classDef performance fill:#DDA0DD,stroke:#333

    %% Application Layer
    subgraph API_Layer
        RustAPI["Rust API"]:::api
        WebAPI["Web/WASM API"]:::api
        FastEmbed["FastEmbed Integration"]:::api
    end

    %% Core Layer
    subgraph Core_Layer
        DB["Database Interface"]:::core
        VectorEngine["Vector Storage Engine"]:::core
        
        subgraph Vector_Processing
            SimCalc["Similarity Calculator"]:::core
            PCA["PCA Decomposition Engine"]:::core
        end
    end

    %% Storage Layer
    subgraph Storage_Layer
        PackedVector["Packed Vector Storage"]:::storage
        
        subgraph Filesystem_Implementations
            NativeFS["Native Filesystem"]:::filesystem
            MemoryFS["In-Memory Filesystem"]:::filesystem
            WebFS["Web Filesystem (OPFS)"]:::filesystem
        end
    end

    %% Performance Metrics
    subgraph Performance_Metrics
        Storage["Storage Efficiency<br/>1.5KB vs 20.6KB JSON"]:::performance
        Compression["Compression Ratios"]:::performance
        Search["Search Performance"]:::performance
    end

    %% Relationships
    RustAPI --> DB
    WebAPI --> DB
    FastEmbed -.-> DB
    
    DB --> VectorEngine
    DB --> Vector_Processing
    
    SimCalc --> VectorEngine
    PCA --> VectorEngine
    
    VectorEngine --> PackedVector
    PackedVector --> Filesystem_Implementations
    
    %% Click Events
    click DB "https://github.com/not-pizza/victor/blob/main/src/db.rs"
    click VectorEngine "https://github.com/not-pizza/victor/blob/main/src/packed_vector.rs"
    click SimCalc "https://github.com/not-pizza/victor/blob/main/src/similarity.rs"
    click PCA "https://github.com/not-pizza/victor/blob/main/src/decomposition.rs"
    click NativeFS "https://github.com/not-pizza/victor/blob/main/src/filesystem/native.rs"
    click MemoryFS "https://github.com/not-pizza/victor/blob/main/src/filesystem/memory.rs"
    click WebFS "https://github.com/not-pizza/victor/blob/main/src/filesystem/web.rs"
    click WebAPI "https://github.com/not-pizza/victor/blob/main/www/src/index.ts"

    %% Legend
    subgraph Legend
        API[API Components]:::api
        CORE[Core Components]:::core
        FS[Filesystem Components]:::filesystem
        PERF[Performance Metrics]:::performance
    end
```
