Pipeline

Processing Pipeline

Architecture and data flow for the transcript processing workflow.

Transcript jobs run as a Lambda and Step Functions pipeline in production. The sandbox uses a local polling orchestrator that preserves the same stage boundaries for development.

flowchart LR
  subgraph Infrastructure
    direction LR
    Client[Client] --> Router[router]
    Router --> StepFunctions[Step Functions]
    StepFunctions --> Callback[Callback result]
    Router --> Client
  end

  subgraph Pipeline[Step Functions pipeline]
    direction TB
    Transcribe[transcribe - ElevenLabs scribe_v2] --> Contextualize[contextualize - optional Bedrock correction]
    Contextualize --> ProfileParticipants[profile-participants - roles and actor_type]
    ProfileParticipants --> Finalize[finalize - CustomerInteraction v1.0]
  end

  StepFunctions --> Transcribe
  Finalize --> Callback
  Transcribe -. pipeline error .-> HandleError
  Contextualize -. pipeline error .-> HandleError
  ProfileParticipants -. pipeline error .-> HandleError
  Finalize -. pipeline error .-> HandleError
  HandleError[handle-error - failed status and failure callback] --> Callback

Stages

StageLambdaResponsibilityTimeout
Request routingrouterValidate the request, create the job record, and start orchestration.30s
TranscriptiontranscribeCall ElevenLabs, normalize provider output, and persist raw artifacts.300s
ContextualizationcontextualizeUse Bedrock to correct domain-specific terms when caller context is provided.60s
Participant profilingprofile-participantsResolve speaker roles and assign actor_type values such as human, ivr, or ai_agent.60s
FinalizationfinalizeBuild and validate CustomerInteraction@v1.0, store the result, and send success callbacks.30s
Error handlinghandle-errorMark the job as failed and send failure callbacks.30s

Data Flow

  1. The caller submits an audio URL and optional transcription hints.
  2. router records the job in DynamoDB and starts the pipeline.
  3. transcribe fetches the audio and stores provider-level transcript artifacts in S3.
  4. contextualize runs only when caller-provided context requires an LLM correction pass.
  5. profile-participants converts provider speakers into Ontopix participant roles.
  6. finalize validates the canonical document with @ontopix/schemas and writes it to S3.

Invariants

  • All AWS resources must run in eu-central-1.
  • Lambda handlers are stateless and must not depend on local disk between invocations.
  • Logs must not include audio content, transcript text, or other personal data.
  • The final output must validate as CustomerInteraction@v1.0.
  • Production API calls and callbacks use IAM SigV4.

Failure Model

Any stage can route to handle-error. The error handler is responsible for persisting the failed status and notifying the callback endpoint when the caller subscribed to failure events.

API Reference

HTTP contract for creating and reading transcript jobs.

Sandbox

Local development workflow for the transcript service sandbox.