> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soundchecklive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Encore.ts backend (api-events) for the Soundcheck platform

The Soundcheck API is an [Encore.ts](https://encore.dev) 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

**1. Prerequisites**

Install Docker Desktop:

* [Docker Desktop for Mac/Windows](https://www.docker.com/products/docker-desktop)
* Node.js 20+ and npm 11.15+ (see repo `packageManager` fields)

**2. Start shared infra**

```bash theme={null}
npm run dev:infra
```

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

**3. Migrate and seed (first time)**

```bash theme={null}
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`

**4. Start api-events**

```bash theme={null}
cd api-events && npm run dev:emulator
```

**5. Verify it's running**

```bash theme={null}
curl http://localhost:4000/health
```

***

## Access points

| Service | URL |
| - | - |
| API (Encore) | [http://localhost:4000](http://localhost:4000) |
| Health check | [http://localhost:4000/health](http://localhost:4000/health) |
| Database | localhost:5433 |
| Clerk emulator | [http://localhost:4711](http://localhost:4711) |
| Azurite (blob storage) | [http://localhost:10000](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

```bash theme={null}
# 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`](https://github.com/soundchecklive/soundcheck-mobile-app/blob/main/api-events/README.md) |

***

## Next steps

> [card] [Setup Guide](https://docs.soundchecklive.io/engineering/backend/setup.md)
>
> Detailed setup instructions

> [card] [Architecture](https://docs.soundchecklive.io/engineering/backend/architecture.md)
>
> Internal architecture

> [card] [Profiles](https://docs.soundchecklive.io/engineering/backend/profiles.md)
>
> Local infra profiles

> [card] [api-events](https://docs.soundchecklive.io/engineering/backend/api-events.md)
>
> Notifications and Pub/Sub fan-out


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.