api-events

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. This page is a map, not a substitute.

Provider secrets and env inventory: api-events operations.

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 and source-backed 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.

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

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

Architecture — layer overview
Database — migrations and seeding
Ledger payable dates — LedgerItem.date vs Event.eventDate
Event chats — Twilio Conversations production runbook
Testing — Vitest + e2e gates
API overview — Encore.ts backend (Go migration complete)

Overview

Backend

Backend integrations

API reference

Frontend

Mobile

Infrastructure

CI/CD

Development

Guides

Reference

What it does

One logical send = one event

DDL ownership

Local development

Webhooks & middleware

Adding work

​What it does

​One logical send = one event

​DDL ownership

​Local development

​Webhooks & middleware

​Adding work

​Related

What it does

One logical send = one event

DDL ownership

Local development

Webhooks & middleware

Adding work

Related