Sandbox

Local development workflow for the transcript service sandbox.

The sandbox emulates AWS services with LocalStack while still using real ElevenLabs and Bedrock APIs. Use non-production credentials and test audio only.

Prerequisites

Docker and Docker Compose.
Node.js 20+ and pnpm.
AWS credentials with Bedrock access.
ElevenLabs API key.

Configure Credentials

cp .sandbox/.env.example .sandbox/.env

Set at least:

AWS_PROFILE=ontopix-dev
ELEVENLABS_API_KEY=sk_...

Optional Bedrock model overrides are documented in .sandbox/.env.example.

Start the Sandbox

task sandbox:start

This builds Lambda bundles, starts LocalStack, provisions local AWS resources, and runs the local orchestrator in the background.

Run the orchestrator in the foreground when debugging state transitions:

task sandbox:orchestrator

Submit a Request

API_URL=$(cat .sandbox/.api-url)

curl "${API_URL}/v1/health"

curl -X POST "${API_URL}/v1/transcripts" \
  -H "Content-Type: application/json" \
  -d '{
    "callback": {
      "url": "https://webhook.site/your-id",
      "events": ["completed", "failed"]
    },
    "metadata": { "test": true },
    "idempotencyKey": "test-001",
    "payload": {
      "input": {
        "audio_url": "https://example.com/audio.mp3"
      },
      "config": {
        "language": "es"
      }
    }
  }'

Check status with the returned job id:

curl "${API_URL}/v1/transcripts/{jobId}"

Useful Tasks

Task	Purpose
`task sandbox:start`	Start LocalStack, provision resources, and run the orchestrator.
`task sandbox:stop`	Stop the sandbox.
`task sandbox:restart`	Restart the sandbox.
`task sandbox:status`	Show sandbox container state.
`task sandbox:setup`	Recreate local AWS resources.
`task sandbox:health`	Check local API health.
`task sandbox:make-request`	Submit a transcript job using task defaults.
`task sandbox:job`	Read a job status by `JOB_ID`.
`task sandbox:debug:logs`	Tail LocalStack logs.
`task sandbox:debug:artifacts`	Download S3 artifacts for a job into `.sandbox/debug/{jobId}/`.
`task sandbox:reset`	Stop, clean volumes, and restart from a clean state.

Sandbox vs Production

Aspect	Production	Sandbox
Orchestration	AWS Step Functions	Local polling orchestrator
AWS services	Real AWS	LocalStack
Authentication	IAM SigV4	None
External APIs	Real ElevenLabs and Bedrock	Real ElevenLabs and Bedrock
Execution	Step Functions state machine	Local sequential orchestration

Processing Pipeline

Architecture and data flow for the transcript processing workflow.

Operations

Development, CI, infrastructure, and escalation guidance for transcript-service.