# patelvivekdev/voyageai-ai-provider architecture

> Architecture diagram of the GitHub repository patelvivekdev/voyageai-ai-provider, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/patelvivekdev/voyageai-ai-provider
- Repository: https://github.com/patelvivekdev/voyageai-ai-provider

## Overview

##### Project type and purpose
- This is an open-source TypeScript SDK (a provider plugin) for the AI SDK, named “voyage-ai-provider.”
- Its sole purpose is to expose a simple interface (text/image/multimodal embedding models) that developers call via the generic `embedMany` function, and under the hood it translates those calls into HTTP requests against the external Voyage AI Embedding API.

##### File structure
- Top‐level directories & files
- src/ – the implementation of the provider
- example/ – sample usage code
- .github/workflows – CI pipeline
- tsup.config.ts, vitest.*.config.js – build & test configs
- package.json, tsconfig.json – package metadata & TS settings
- src/ contents
- index.ts – entry point, exports factory function
- voyage-provider.ts – core class that holds API key & model factories
- voyage-*-model.ts & voyage-*-settings.ts – adapters for each embedding flavor (text, image, multimodal)
- voyage-error.ts – custom error handling
- Tests (vitest) alongside each model file

##### README for additional insights
- Explains how to import and configure the provider with an API key
- Shows usage patterns for text, image, and multimodal embedding
- Points to the Voyage AI REST API (the external service)

##### Elements
[Client App] → [AI SDK Interface] → [Voyage AI Provider Library] → [Voyage REST API]
- Blue for in-process modules (Client/SDK/Provider)
- Green for external service (Voyage REST API)
- Orange for config data store
- Grey for build/CI pipeline (optional, off to the side)
- Annotations for key technologies by component (e.g., “TypeScript”, “node-fetch/axios”, “tsup”, “Vitest”, “GitHub Actions”).

##### Additional detail
- You may optionally show the directory structure under [Voyage AI Provider] to highlight src/, tests, tsup config, and example/ usage.
- If desired, include a small inset showing the HTTP request format (headers with API key, JSON payload with inputs, JSON response with embeddings).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% In-Process Modules
    subgraph "In-Process Modules"
        direction TB
        ClientApp["Client Application"]:::inproc
        AI_SDK["AI SDK Interface<br/>(embedMany)"]:::inproc
        subgraph "Voyage AI Provider Library"
            direction TB
            ProviderCore["Provider Core<br/>(voyage-provider.ts)"]:::inproc
            TextModel["Text Embedding Adapter<br/>(voyage-embedding-model.ts)"]:::inproc
            TextSettings["Text Embedding Config<br/>(voyage-embedding-settings.ts)"]:::inproc
            MultiModel["Multimodal Embedding Adapter<br/>(voyage-multimodal-embedding-model.ts)"]:::inproc
            MultiSettings["Multimodal Embedding Config<br/>(voyage-multimodal-embedding-settings.ts)"]:::inproc
            ErrorModule["Custom Error Handling<br/>(voyage-error.ts)"]:::inproc
        end
    end

    %% Configuration and External API
    Config["Configuration Store<br/>(VOYAGE_API_KEY)"]:::config
    ExternalAPI["Voyage REST API"]:::external

    %% Build & CI Pipeline
    subgraph "Build & CI Pipeline"
        direction TB
        TSUP["TSup Config<br/>(tsup.config.ts)"]:::pipeline
        VitestEdge["Vitest Edge Config<br/>(vitest.edge.config.js)"]:::pipeline
        VitestNode["Vitest Node Config<br/>(vitest.node.config.js)"]:::pipeline
        CI["GitHub Actions CI<br/>(.github/workflows/CI.yml)"]:::pipeline
        Package["package.json & tsconfig.json"]:::pipeline
        Tests1["Text Model Tests<br/>(voyage-embedding-model.test.ts)"]:::pipeline
        Tests2["Multimodal Model Tests<br/>(voyage-multimodal-embedding-model.test.ts)"]:::pipeline
    end

    %% Main Flow
    ClientApp -->|"calls embedMany()"| AI_SDK
    AI_SDK -->|"delegates to provider"| ProviderCore
    Config -->|"injects key"| ProviderCore
    ProviderCore -->|"uses adapter"| TextModel
    ProviderCore -->|"uses adapter"| MultiModel
    TextModel -->|"reads settings"| TextSettings
    MultiModel -->|"reads settings"| MultiSettings
    ProviderCore ==>|"HTTP Request"| ExternalAPI
    ExternalAPI ==>|"HTTP Response"| ProviderCore
    ProviderCore -->|"returns embeddings"| AI_SDK
    AI_SDK -->|"returns embeddings"| ClientApp

    %% Tests connections
    Tests1 -->|"tests"| TextModel
    Tests2 -->|"tests"| MultiModel

    %% Click Events
    click ClientApp "https://github.com/patelvivekdev/voyageai-ai-provider/tree/master/example/"
    click AI_SDK "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/src/index.ts"
    click ProviderCore "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/src/voyage-provider.ts"
    click TextModel "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/src/voyage-embedding-model.ts"
    click TextSettings "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/src/voyage-embedding-settings.ts"
    click MultiModel "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/src/voyage-multimodal-embedding-model.ts"
    click MultiSettings "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/src/voyage-multimodal-embedding-settings.ts"
    click ErrorModule "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/src/voyage-error.ts"
    click Tests1 "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/src/voyage-embedding-model.test.ts"
    click Tests2 "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/src/voyage-multimodal-embedding-model.test.ts"
    click TSUP "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/tsup.config.ts"
    click VitestEdge "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/vitest.edge.config.js"
    click VitestNode "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/vitest.node.config.js"
    click CI "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/.github/workflows/CI.yml"
    click Package "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/package.json"
    click Package "https://github.com/patelvivekdev/voyageai-ai-provider/blob/master/tsconfig.json"

    %% Styles
    classDef inproc fill:#b3cde0,stroke:#6497b1,color:#03396c
    classDef external fill:#c7e9c0,stroke:#74c476,color:#236f20
    classDef config fill:#fdd0a2,stroke:#fb8c00,color:#8c2d04
    classDef pipeline fill:#e0e0e0,stroke:#888888,color:#333333
```
