API Setup

This guide covers setting up the Soundcheck API (api-events) for local development.

Prerequisites

Tool	Purpose	Installation
Docker Desktop	Postgres, Azurite, Clerk emulator	Download
Node.js 20+	Encore.ts runtime	Devcontainer or nodejs.org
npm 11.15+	Package manager	Upgraded by repo CI scripts

Encore CLI is required for npm run dev:emulator. The devcontainer image includes it; otherwise install from encore.dev.

Quick start

Install dependencies

cd api-events && npm install

Start shared infra

npm run dev:infra

Starts Postgres (:5433), Azurite (:10000), and Clerk emulator (:4711) from dev/docker-compose.yml.

Migrate and seed (first time)

cd api-events
export DATABASE_URL='postgresql://postgres:postgres@localhost:5433/soundcheck?schema=public'
npm run db:migrate
npm run db:seed:demo-full
docker compose -p api -f dev/docker-compose.yml restart clerk-emulator

Start api-events

cd api-events && npm run dev:emulator

Verify it's running

curl http://localhost:4000/health

For full-stack web dev, also run cd web && npm run dev:emulator (proxies to Encore on :4000). See .agents/skills/local-clerk-emulator/SKILL.md.

Shared infra (`dev:infra`)

# Repo root — Postgres + Azurite + Clerk emulator (no Encore container)
npm run dev:infra

# Stop
docker compose -p api -f dev/docker-compose.yml down

Service	Port
Postgres	5433
Azurite	10000
Clerk emulator	4711

Environment variables

npm run dev:emulator sets the documented local env (Clerk emulator URLs, stub providers, DATABASE_URL). For manual runs:

ENVIRONMENT=development
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/soundcheck?schema=public
CLERK_SECRET_KEY=sk_test_emulate
CLERK_API_BASE_URL=http://localhost:4711
CLERK_WEBHOOK_SECRET=whsec_c291bmRjaGVjay1sb2NhbC1jbGVyay13ZWJob29r

Provider stubs (TWILIO_USE_STUB_SMS, SENDGRID_USE_STUB_EMAIL, etc.) default to on in dev:emulator. See api-events operations for the full secrets inventory.

Database access

Property	Value
Host	localhost
Port	5433
Database	soundcheck
User	postgres
Password	postgres

psql -h localhost -p 5433 -U postgres -d soundcheck

Port	Purpose
5432	Reserved for native PostgreSQL
5433	Docker Postgres (`dev:infra`)
5434	Integration/e2e test database

Troubleshooting

Port 4000 already in use

lsof -ti:4000
lsof -ti:4000 | xargs kill -9

Or run Encore on another port: encore run --port=4001

Database connection refused

Ensure infra is running:

npm run dev:infra
docker compose -p api -f dev/docker-compose.yml ps

Prisma client errors

Regenerate after schema changes:

cd api-events && npm run prisma:generate

Overview

Backend

Backend integrations

API reference

Frontend

Mobile

Infrastructure

CI/CD

Development

Guides

Reference

Prerequisites

Quick start

Shared infra (`dev:infra`)

Environment variables

Database access

Troubleshooting

Next steps

Profiles

Database

​Prerequisites

​Quick start

​Shared infra (dev:infra)

​Environment variables

​Database access

​Troubleshooting

​Next steps

Profiles

Database

Prerequisites

Quick start

Shared infra (`dev:infra`)

Environment variables

Database access

Troubleshooting

Next steps