deepgram-reference-architecture

name	deepgram-reference-architecture
description	Implement Deepgram reference architecture for scalable transcription systems. Use when designing transcription pipelines, building production architectures, or planning Deepgram integration at scale. Trigger: "deepgram architecture", "transcription pipeline", "deepgram system design", "deepgram at scale", "enterprise deepgram", "deepgram queue".
allowed-tools	Read, Write, Edit, Bash(npm:*)
version	1.13.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","deepgram","architecture","scaling"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Deepgram Reference Architecture

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

import express from 'express';
import { createClient } from '@deepgram/sdk';

const app = express();
app.use(express.json());

const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);

// Direct API call — best for short files (<60s)
app.post('/api/transcribe', async (req, res) => {
  const { url, model = 'nova-3', diarize = false } = req.body;

  try {
    const { result, error } =  deepgram...(
      { url },
      { model, : , diarize, : diarize }
    );
     (error)  res.().({ : error. });

    res.({
      : result..[].[].,
      : result..[].[].,
      : result..,
      : result..,
      : diarize ? result.. : ,
    });
  }  (: ) {
    res.().({ : err. });
  }
});