| name | elevenlabs-reference-architecture |
| description | Implement an ElevenLabs reference architecture for production TTS/voice
applications. Use when designing new ElevenLabs integrations, reviewing
project structure, or building a scalable audio generation service.
Trigger with "elevenlabs architecture", "elevenlabs project structure",
"how to organize elevenlabs", "TTS service architecture",
"elevenlabs design patterns", "voice API architecture".
|
| allowed-tools | Read |
| version | 1.6.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","voice","ai","elevenlabs","architecture","patterns"] |
| compatibility | Designed for Claude Code |
ElevenLabs Reference Architecture
Overview
Production-ready architecture for ElevenLabs TTS/voice applications. Covers project
layout, service layers, caching, streaming, and multi-model orchestration. The full
code for each layer lives in references/ so this file stays a navigable map; drill
into a reference file when you need the exact implementation.
Prerequisites
- Understanding of layered architecture patterns
- ElevenLabs SDK knowledge (see
elevenlabs-sdk-patterns)
- TypeScript project with async patterns
- Redis (optional, for distributed caching)
- Auth: an ElevenLabs API key exported as
ELEVENLABS_API_KEY (read by the
config layer). This is the only ElevenLabs credential — your app's own request
auth (middleware/auth.ts) is separate and unrelated.
Instructions
Build the service in six layers. Each step below is the high-level move; the
verbatim code and diagrams are in the linked reference files.
Step 1: Lay out the project
Split the codebase into elevenlabs/ (client, config, models, errors, types),
services/ (tts, voice, audio, cache), api/ (routes + middleware), queue/, and
monitoring/. See the full project tree.
Step 2: Configuration layer
Define an environment-aware ElevenLabsConfig — dev uses the cheap/fast
eleven_flash_v2_5 and small output format; production uses eleven_multilingual_v2
at higher quality, more concurrency, and a larger cache. loadConfig() merges the
per-environment defaults with ELEVENLABS_API_KEY. Full interface and ENV_CONFIGS:
implementation walkthrough.
Step 3: TTS service layer
Wrap the SDK client in a TTSService that owns a singleton client and a p-queue
sized to maxConcurrency (this is what prevents 429s). generate() supports both
streaming and buffered convert, logs latency, and routes errors through
classifyError. generateLongText() splits on sentence boundaries under the 5000-char
limit to preserve prosody. Full class:
implementation walkthrough.
Step 4: Voice management service
