> Documentation index: https://docs.mayur.live/llms.txt

# Voiceflow API Overview

Understand the architecture, tech stack, and end-to-end lifecycle of audio feedback processing in Voiceflow.

Voiceflow API is a REST backend where customers submit short voice notes and admins review transcribed and analysed recordings. The API coordinates direct-to-storage uploads, speech-to-text conversion, and sentiment analysis without routing raw audio streams through the application server.

## What is Voiceflow API

Voiceflow API provides endpoints for customer feedback collection and administrative review. Customers register an intended recording, upload audio directly to private object storage using a signed URL, and confirm completion. 

The API processes audio asynchronously in background workers:
- Each recording is transcribed in its original language and translated to English.
- English transcripts are analysed for sentiment labels and scores.
- Admins can query feedback, filter recordings, review transcripts and sentiment, replay audio, and reprocess failed jobs.

## System Architecture and Flow

The application is structured into an HTTP interface, a database, an S3-compatible storage layer, and an asynchronous processing engine:

1. **HTTP Layer:** An Express 5 application (`app`) routes API traffic through `apiRouter`, exposes health checks, handles Better Auth endpoints, and mounts the Inngest handler.
2. **Registration:** A customer calls `POST /api/feedback`. The server validates request limits, inserts a `Feedback` record in `UPLOADING` status, and generates a pre-signed S3 upload URL with a fixed content type and size limit. Audio path format is `{userId}/{feedbackId}.{ext}`.
3. **Upload:** The client uploads audio directly to S3-compatible storage with an HTTP `PUT` request. Audio payload never passes through Express.
4. **Confirmation:** The client calls `POST /api/feedback/:id/complete`. The API verifies the file exists in storage and matches the registered byte size, updates the record status to `UPLOADED`, and dispatches a `feedback/uploaded` event to Inngest.
5. **Background Pipeline:** Inngest runs `/api/inngest` to execute background steps: claiming the recording, performing dual transcription via Sarvam, running sentiment analysis on the English text via an LLM, and updating the database.

## Feedback Statuses

A recording moves through the following lifecycle states:

| Status | Description |
| --- | --- |
| `UPLOADING` | Feedback record created. The client holds a signed upload URL valid for 15 minutes. |
| `UPLOADED` | Client completed upload and called `/complete`. File size verified in storage, queued for processing. |
| `PROCESSING` | Inngest pipeline has claimed the recording and is running transcription or sentiment analysis. |
| `FAILED` | An error occurred during processing. Contains a specific pipeline error code. |
| `EXPIRED` | Customer did not complete upload within the 15-minute window. Set during cleanup. |

## Pipeline Error Codes

When a background job fails and cannot proceed, the feedback record is marked `FAILED` with an error code:

| Error Code | Description |
| --- | --- |
| `SPEECH_REJECTED` | Sarvam rejected the audio file format or the request contained an invalid Sarvam API key. |

## Technology Stack

The service uses the following libraries, runtimes, and external platforms:

| Area | Choice |
| --- | --- |
| Runtime | Node.js 22 or newer (ESM) |
| Framework | Express 5, TypeScript |
| Authentication | Better Auth with email/password and `admin` plugin |
| Database | PostgreSQL managed with Prisma 7 (`pg` adapter) |
| Audio Storage | S3-compatible object storage (AWS S3, Supabase Storage, Cloudflare R2, MinIO) |
| Speech to Text | Sarvam `saaras:v4` (supporting English and Indian languages) |
| Sentiment Analysis | Vercel AI SDK with OpenRouter (default model: `openai/gpt-4o-mini`) |
| Background Jobs | Inngest (served at `/api/inngest`) |
| Email Service | Resend |
| Validation | zod |
| Logging | pino and pinoHttp |