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 in public documentation.
What it needs
Requires @deepgram/sdk, bullmq, express, ioredis 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--24ead0