Operations

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

All repeatable operations are exposed through Taskfile.yaml. Prefer task commands over direct tool invocations so humans, agents, and CI use the same interface.

First-Time Setup

task setup

This prepares local env files, authenticates to the private package registry, and installs dependencies.

Development Commands

Task	Purpose
`task --list`	Show available tasks.
`task setup:install`	Install project dependencies.
`task build:lambda`	Build Lambda deployment packages.
`task build:clean`	Remove build artifacts.

Quality Gates

Task	Purpose
`task lint:check`	Run code quality checks without modifying files.
`task lint:types`	Run TypeScript type checking.
`task lint:format`	Check Prettier formatting.
`task lint:all`	Run all lint checks.
`task test:unit`	Run unit tests.
`task test:integration`	Run integration tests.
`task test:all`	Run unit and integration tests. Set `INCLUDE_E2E=1` to include e2e tests.
`task ci:all`	Run local CI: lint, tests, and build.

Infrastructure

Infrastructure lives under .infra/ and is managed with Terraform tasks.

Task	Purpose
`task infra:init`	Initialize Terraform for the selected `ENV`.
`task infra:plan`	Show Terraform changes for the selected `ENV`.
`task infra:apply`	Apply Terraform changes for the selected `ENV`. Requires human approval.
`task infra:fmt`	Check Terraform formatting.
`task infra:validate`	Validate Terraform configuration.

Set ENV=dev, ENV=pre, or ENV=prod before environment-specific operations.

Required Environment

Root .env values are used by setup and infrastructure tasks:

Variable	Purpose
`AWS_PROFILE`	AWS profile for authenticated operations.
`ENV`	Target environment for infrastructure and config tasks.
`NPM_TOKEN`	CodeArtifact token for private package installation.
`ELEVENLABS_API_KEY`	Transcription provider credential.

Sandbox-specific credentials live in .sandbox/.env.

Non-Negotiable Constraints

Keep all cloud resources in eu-central-1.
Do not log audio content, transcript text, or personal data.
Validate final output against @ontopix/schemas.
Preserve stateless Lambda behavior.
Use SigV4 for production inbound API calls and callbacks.

Human Approval Required

Request explicit approval before:

Running task infra:apply or any destructive infrastructure command.
Changing the CustomerInteraction@v1.0 schema contract.
Adding or removing transcription providers.
Changing the processing pipeline contract.
Touching production data or credentials.

Sandbox

Local development workflow for the transcript service sandbox.

Transcript Service

Internal service that turns audio URLs into validated CustomerInteraction@v1.0 documents.