API Overview

The Soundcheck API is an Encore.ts service (api-events/) that serves the public REST API, owns PostgreSQL DDL, and fans out notifications over GCP Pub/Sub. It powers the web and mobile apps on port 4000.

Quick start

Prerequisites

Install Docker Desktop:

Docker Desktop for Mac/Windows
Node.js 20+ and npm 11.15+ (see repo packageManager fields)

Start shared infra

npm run dev:infra

Starts Postgres (:5433), Azurite (:10000), and the Clerk emulator (:4711).

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

Then restart the Clerk emulator so personas load: 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

Access points

Service	URL
API (Encore)	http://localhost:4000
Health check	http://localhost:4000/health
Database	localhost:5433
Clerk emulator	http://localhost:4711
Azurite (blob storage)	http://localhost:10000

Technology stack

Component	Technology
Runtime	Encore.ts (Node.js)
Language	TypeScript
Database	PostgreSQL 14
ORM	Prisma (`@prisma/client`)
Auth	Clerk (JWT)
Notifications	GCP Pub/Sub → SMS / email / push

Project structure

api-events/
├── src/
│   ├── systems/          # Domain modules (operations + endpoints)
│   ├── processors/       # Pub/Sub notification processors
│   ├── handlers/         # Pub/Sub subscriptions
│   ├── webhooks/         # Inbound provider webhooks
│   ├── endpoints/        # Route registry + shared HTTP wiring
│   ├── db/               # Prisma client, schema, migrations
│   ├── config/           # Secrets and env config
│   └── encore.service.ts # Service bootstrap (middleware, migrate on boot)
├── scripts/              # Migrations, seed, e2e runners
└── prisma.config.ts      # Prisma generate config

Shared local infra (Postgres, Clerk emulator, Azurite) lives in dev/docker-compose.yml and is started via npm run dev:infra at the repo root.

Core resources

REST paths follow /api/v1/.... Representative domains:

Resource	Path prefix	Description
Users	`/api/v1/users`	User profiles and preferences
Organizations	`/api/v1/organizations`	Bands, venues, production companies
Events	`/api/v1/events`	Gigs, rehearsals, shows
Invitations	`/api/v1/invitations`	Event invites with status tracking
Calllists	`/api/v1/calllists`	Reusable team rosters
Setlists	`/api/v1/setlists`	Song lists and sets
Positions	`/api/v1/positions`	Musician roles
Subscriptions	`/api/v1/subscriptions`	Billing and plan management

The path inventory is the Encore endpoint declarations; api-events/routes.json holds domain overrides.

Webhooks

Provider	Endpoint	Purpose
Clerk	`/webhooks/clerk`	User signup, org membership changes
Stripe	`/webhooks/stripe`	Subscription and payment events
Cleo Pay	`/webhooks/cleo`	Bank-account verification status
Twilio	`/webhooks/twilio`	SMS reply handling for invitations
Twilio Conversations	`/webhooks/twilio/conversations`	Event group-chat `onMessageAdded` (push + last-message)

Development commands

# Shared infra (repo root)
npm run dev:infra

# api-events
cd api-events
npm run dev:emulator          # Encore on :4000 with local Clerk emulator env
npm run db:migrate            # Apply Prisma migrations
npm run db:seed:demo-full     # Rich local demo dataset
npm run test                  # Unit tests (Vitest)
npm run test:e2e              # Full e2e regression against :4000
npm run checks                # typecheck + lint + format + coverage

Source of truth

What	Where
Database schema + migrations	`api-events/src/db/schema.prisma`, `api-events/src/db/migrations/`
Route inventory	Encore endpoint declarations + `api-events/routes.json`
OpenAPI snapshot	`docs/openapi/soundcheck.json` (from `npm run openapi:emit`)
Deep architecture	`api-events/README.md`

Next steps

Setup Guide

Detailed setup instructions

Architecture

Internal architecture

Profiles

Local infra profiles

api-events

Notifications and Pub/Sub fan-out

Overview

Backend

Backend integrations

API reference

Frontend

Mobile

Infrastructure

CI/CD

Development

Guides

Reference

Quick start

Access points

Technology stack

Project structure

Core resources

Webhooks

Development commands

Source of truth

Next steps

Setup Guide

Architecture

Profiles

api-events

​Quick start

​Access points

​Technology stack

​Project structure

​Core resources

​Webhooks

​Development commands

​Source of truth

​Next steps

Setup Guide

Architecture

Profiles

api-events

Quick start

Access points

Technology stack

Project structure

Core resources

Webhooks

Development commands

Source of truth

Next steps