Agent skill · software engineering · jeremylongshore
deepgram-reference-architecture
Implement Deepgram reference architecture for scalable transcription
Why this skill is useful
Adds executable scripts for various Deepgram transcription architectures that aren't available in public documentation.
What it needs
Requires npm, redis installed locally. Requires deepgram account access. About 5k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Deepgram Reference Architecture Prerequisites A documented audio/transcript data flow, consent/retention policy, approved environment boundaries, and service/data owners. Reviewed interfaces for auth, media ingestion, callbacks, observability, storage, and incident response. Examples Model a development producer that validates media metadata, sends a request using a scoped project key, receives a signed callback, and records only correlation/state metrics. Promote the same versioned contract through staging before a production canary, retaining a dead-letter/recovery owner and excluding audio/transcript content from telemetry. Overview Four reference architectures for Deepgram transcription at scale: synchronous REST for short files, async queue (BullMQ) for batch processing, WebSocket proxy for real-time streaming, and a hybrid router that auto-selects the best pattern based on audio duration. Architecture Selection Guide Pattern Best For Latency Throughput Complexity --------- ---------- --------- ------------ ------------ Sync REST Files <60s, low volume Low Low Simple Async Queue Batch, files >60s Medium High Medium WebSocket Proxy Live audio, real-time Real-time Medium Medium Hybrid Router Mixed workloads Varies High High Callback Files >5min, fire-and-forget N/A Very High Low Instructions Step 1: Synchronous REST Pattern Step 2: Async Queue Pattern (BullMQ) Step 3: WebSocket Proxy for Real-Time Step 4: Hybrid Router Step 5: Architecture Diagram Output Sync REST endpoint for short files BullMQ queue with workers for batch processing WebSocket proxy for real-time streaming Hybrid router with auto-mode selection Architecture diagram Error Handling Issue Cause Solution ------- ------- ---------- Sync timeout on large file Wrong pattern selected Use async queue or callback Queue backlog growing Workers overloaded Scale workers, increase concurrency WebSocket disconnects Network instability Auto-reconnect with backoff Callback not received Endpoint unreachable Check …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/deepgram-reference-architecture