> ## 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-events

> Encore.ts system of record and notification fan-out service

`api-events` is the **system of record** for Soundcheck: full public REST API on `:4000`, PostgreSQL DDL owner, direct Pub/Sub publisher, and notification fan-out (SMS, email, push).

> **Canonical deep-dive:** [`api-events/README.md`](https://github.com/soundchecklive/soundcheck-mobile-app/blob/main/api-events/README.md). This page is a map, not a substitute.

Provider secrets and env inventory: [api-events operations](https://docs.soundchecklive.io/engineering/backend/api-events-operations.md).

## What it does

**HTTP.** Every public path is served by Encore endpoints under `src/systems/`. The endpoint declarations are the inventory, and `routes.json` holds the domain overrides; unknown paths return Encore 404.

**Notifications.** Operations publish directly to Pub/Sub after local work; a shared transactional outbox is not implemented. Some publishers await confirmation and others detach publication. Availability processors demonstrate channel/device fan-out, but failure policies vary by feature. See the [durability contract](./async-durability-patterns) and [source-backed assessment](./async-workflow-assessment) for the target and migration priorities.

## One logical send = one event

Notification consumers use these records to track attempts and deduplicate completed events:

* **`processed_events`** — generic inbox keyed by `(event_id, consumer_name)`.
* **`notification_deliveries`** — notification-attempt audit, including failed outcomes.

Helpers: `src/db/processedEvent.ts`, `src/db/notificationDelivery.ts`.

An inbox does not serialize concurrent provider calls or close the crash window after a provider succeeds. Required workflows need the operation identities, claims and recovery policy specified in the [durability contract](./async-durability-patterns).

## DDL ownership

Schema and migrations:

```
api-events/src/db/schema.prisma
api-events/src/db/migrations/
```

* Applies on Encore boot (`migrateDeployOrThrow()`).
* Explicit local apply: `npm run db:migrate`.
* No Encore `SQLDatabase` declaration (avoids a second applier).

## Local development

```bash theme={null}
npm run dev:infra                              # Postgres + Azurite + Clerk emulator
cd api-events && npm run db:migrate            # first time / after schema changes
cd api-events && npm run db:seed:demo-full     # demo personas
docker compose -p api -f dev/docker-compose.yml restart clerk-emulator
cd api-events && npm run dev:emulator          # Encore on :4000
```

## Webhooks & middleware

Inbound webhooks (`/webhooks/clerk`, `/webhooks/stripe`, …) use `auth: false` and verify provider signatures in operations. HTTP endpoints run middleware (error capture → Sentry, user context); Pub/Sub subscription handlers are self-instrumenting.

## Adding work

| Change | Where to start |
| - | - |
| New REST route | `src/systems/<domain>/` — operation + endpoint; the folder name is the domain unless `routes.json` overrides it |
| New Pub/Sub notification | Mirror `availabilityRequest` family — event, topic, processor, handler |
| Schema change | `src/db/schema.prisma` + migration; `npm run db:migrate` |

Agent conventions: `.agents/skills/encore-port/SKILL.md`

## Related

* [Architecture](https://docs.soundchecklive.io/engineering/backend/architecture.md) — layer overview
* [Database](https://docs.soundchecklive.io/engineering/backend/database.md) — migrations and seeding
* [Ledger payable dates](https://docs.soundchecklive.io/engineering/backend/ledger-payable-dates.md) — `LedgerItem.date` vs `Event.eventDate`
* [Event chats](./event-chats) — Twilio Conversations production runbook
* [Testing](https://docs.soundchecklive.io/engineering/backend/testing.md) — Vitest + e2e gates
* [API overview](https://docs.soundchecklive.io/engineering/backend/overview.md) — Encore.ts backend (Go migration complete)


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