| 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. splits on sentence boundaries under the 5000-char
limit to preserve prosody. Full class:
.
