# elevenlabs/elevenlabs-js architecture

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

- Interactive diagram: https://gitdiagram.com/elevenlabs/elevenlabs-js
- Repository: https://github.com/elevenlabs/elevenlabs-js

## Overview

##### Project type and purpose
- This is a Node.js client-side SDK (an NPM library) for ElevenLabs’ text-to-speech HTTP API.
- It’s generated by Fern and exposes a typed, promise/stream-based interface (with retries, timeouts, streaming audio, and wrappers for playing audio).

##### File structure
- Top-level:
– src/
- core/        ← runtime abstractions & fetch layer (Fetcher, streaming, form-data, schemas)
- api/         ← generated API resource clients, grouped by service (textToSpeech, voices, conversationalAi, etc.)
- serialization/← data serializers / request builders / type definitions mirroring src/api
- wrapper/     ← ergonomic entry points (ElevenLabsClient, play, stream, webhooks)
- index.ts & version.ts ← public API surface
– .mock/        ← AsyncAPI/OpenAPI definitions & fixtures for a mock server
– scripts/      ← build-time helpers (e.g. rename-to-esm-files.js)
– tests/        ← Jest unit & integration tests for fetcher, schemas, custom scenarios
– CI & config: jest.config.mjs, tsconfig.json, .github/workflows/ci.yml

##### README for additional insights
- Confirms it’s an SDK with:
– HTTP API integration (fetch + retries + timeouts)
– Streaming support
– Runtime compatibility (Node.js, Cloudflare, Deno, Bun)
– External dependencies for audio playback (mpv, ffmpeg)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Application
    Consumer["Consumer Application"]:::consumer

    %% SDK Layers
    subgraph "Public API Surface"
        PublicAPI["src/index.ts\nsrc/version.ts"]:::publicapi
    end

    subgraph "Wrapper Layer"
        WrapperLayer["src/wrapper"]:::wrapper
    end

    subgraph "API Client Layer"
        APIClientLayer["src/api"]:::api
    end

    subgraph "Serialization Layer"
        SerializationLayer["src/serialization"]:::serialization
    end

    subgraph "Core Runtime & Fetcher"
        CoreLayer["src/core"]:::core
    end

    %% External Services & Tools
    subgraph "External Services"
        ElevenLabsHTTP["ElevenLabs HTTP API"]:::external
        AudioPlayback["Audio Playback Tools\n(mpv, ffmpeg)"]:::external
    end

    %% Testing & Mock Server
    subgraph "Testing & Mock"
        MockServer[".mock"]:::mock
        Tests["Tests (Jest)"]:::test
    end

    %% CI/CD
    CICD["CI/CD\n(GitHub Actions)"]:::cicd

    %% Connections
    Consumer -->|uses| PublicAPI
    PublicAPI -->|calls| WrapperLayer
    WrapperLayer -->|delegates to| APIClientLayer
    APIClientLayer -->|uses| SerializationLayer
    SerializationLayer -->|formats data for| CoreLayer
    CoreLayer -->|sends requests to| ElevenLabsHTTP
    CoreLayer -->|↔ tests via| MockServer
    WrapperLayer -->|plays audio via| AudioPlayback
    CICD -->|runs| Tests
    CICD -->|uses mocks| MockServer

    %% Click Events
    click CoreLayer "https://github.com/elevenlabs/elevenlabs-js/tree/main/src/core"
    click WrapperLayer "https://github.com/elevenlabs/elevenlabs-js/tree/main/src/wrapper"
    click APIClientLayer "https://github.com/elevenlabs/elevenlabs-js/tree/main/src/api"
    click SerializationLayer "https://github.com/elevenlabs/elevenlabs-js/tree/main/src/serialization"
    click PublicAPI "https://github.com/elevenlabs/elevenlabs-js/blob/main/src/index.ts"
    click MockServer "https://github.com/elevenlabs/elevenlabs-js/blob/main/.mock"
    click CICD "https://github.com/elevenlabs/elevenlabs-js/blob/main/.github/workflows/ci.yml"
    click Tests "https://github.com/elevenlabs/elevenlabs-js/tree/main/tests"

    %% Styles
    classDef consumer fill:#f9f,stroke:#333,stroke-width:1px
    classDef publicapi fill:#cff,stroke:#333,stroke-width:1px
    classDef wrapper fill:#cfc,stroke:#333,stroke-width:1px
    classDef api fill:#ccf,stroke:#333,stroke-width:1px
    classDef serialization fill:#fcf,stroke:#333,stroke-width:1px
    classDef core fill:#f96,stroke:#333,stroke-width:1px
    classDef external fill:#f99,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef mock fill:#eee,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
    classDef test fill:#ddd,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
    classDef cicd fill:#ff9,stroke:#333,stroke-width:1px
```
