Full Stack Development

This guide covers the day-to-day workflow for running Soundcheck services together. For per-component environment variables and one-time setup, see Environment Setup.

Architecture Overview

┌─────────────────┐     ┌─────────────────┐
│   Mobile App    │     │    Web App      │
│  (Expo/React    │     │   (Next.js)     │
│   Native)       │     │   Port 3000     │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └───────────┬───────────┘
                     │
                     ▼
           ┌─────────────────┐
           │   api-events    │
           │  (Encore.ts)    │
           │   Port 4000     │
           └────────┬────────┘
                    │
         ┌──────────┴──────────┐
         ▼                     ▼
┌─────────────────┐   ┌─────────────────┐
│   PostgreSQL    │   │ Clerk emulator  │
│   Port 5433     │   │   Port 4711     │
└─────────────────┘   └─────────────────┘

Shared infra (npm run dev:infra) starts Postgres, Azurite, and the Clerk emulator from dev/docker-compose.yml.

Quick Start

Start shared infrastructure

npm run dev:infra

Migrate and seed the database

cd api-events
export DATABASE_URL='postgresql://postgres:postgres@localhost:5433/soundcheck?schema=public'
npm run db:migrate
npm run db:seed:demo-full

Start api-events

cd api-events && npm run dev:emulator

Wait for health:

curl http://localhost:4000/health

Start the Web App

In a new terminal:

cd web && npm run dev:emulator

Start the Mobile App

In another terminal:

EXPO_PUBLIC_API_URL=http://localhost:4000 npm start

Access Points

Service	URL	Notes
Mobile App	Expo CLI	Press `i` for iOS, `a` for Android
Web App	http://localhost:3000	Next.js dev server
api-events	http://localhost:4000	Encore HTTP API (system of record)
Clerk emulator	http://localhost:4711	Local auth personas
Database	localhost:5433	PostgreSQL

Environment Configuration

Full per-component variables live in Environment Setup. The essentials for the local stack:

Mobile (.env at root): EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY, EXPO_PUBLIC_API_URL=http://localhost:4000. For a physical device, use your machine’s LAN IP (or the Expo tunnel).
Web (web/.env.local): NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY, NEXT_PUBLIC_API_URL=/api-proxy/api/v1, BACKEND_API_URL=http://localhost:4000.
api-events: DATABASE_URL (see migrate step above); npm run dev:emulator wires Clerk to :4711.

The web /api-proxy rewrite is dev-only (NODE_ENV === "development") — it forwards to BACKEND_API_URL to avoid CORS. A prod build can’t use it. With db:seed:demo-full + the Clerk emulator, sign-in lists demo personas without manual DB inserts.

Development Workflow

Making API Changes

Work in api-events/src/. Encore hot-reloads on save when using npm run dev:emulator. After route contract changes, run npm run openapi:emit and npm run openapi:parity.

Making Web Changes

Changes auto-reload with Next.js hot reload. Regenerate the typed API client after OpenAPI changes: npm run generate:api-client (also runs on predev).

Making Mobile Changes

Changes auto-reload with Expo’s hot reload.

Database Operations

View Database

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

Migrate & Seed

cd api-events
export DATABASE_URL='postgresql://postgres:postgres@localhost:5433/soundcheck?schema=public'
npm run db:migrate
npm run db:seed:baseline    # minimal roles/plans
npm run db:seed:demo-full   # demo org + Clerk personas

Reset Database

docker compose -p api -f dev/docker-compose.yml down -v
npm run dev:infra
cd api-events && npm run db:migrate && npm run db:seed:demo-full

Troubleshooting

api-events can't connect to database

Ensure shared infra is running:

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

Web app can't reach API

Check api-events is running: curl http://localhost:4000/health
Verify BACKEND_API_URL=http://localhost:4000 in web/.env.local
Clear .next/ after changing NEXT_PUBLIC_* vars

Mobile app can't reach API

Use your computer’s IP instead of localhost
Ensure phone/emulator is on same network
Check firewall settings

Port already in use

lsof -ti:4000 | xargs kill -9   # api-events
lsof -ti:3000 | xargs kill -9   # web

Authentication issues

Ensure all services use the same Clerk credentials (or the local emulator via npm run dev:emulator launchers).

Stopping All Services

docker compose -p api -f dev/docker-compose.yml down
# Web, api-events, and mobile stop with Ctrl+C

To remove the database volume: add -v to the docker compose down command above.

Overview

Backend

Backend integrations

API reference

Frontend

Mobile

Infrastructure

CI/CD

Development

Guides

Reference

Full Stack Development

Architecture Overview

Quick Start

Access Points

Environment Configuration

Development Workflow

Making API Changes

Making Web Changes

Making Mobile Changes

Database Operations

View Database

Migrate & Seed

Reset Database

Troubleshooting

Stopping All Services

​Architecture Overview

​Quick Start

​Access Points

​Environment Configuration

​Development Workflow

​Making API Changes

​Making Web Changes

​Making Mobile Changes

​Database Operations

​View Database

​Migrate & Seed

​Reset Database

​Troubleshooting

​Stopping All Services

Architecture Overview

Quick Start

Access Points

Environment Configuration

Development Workflow

Making API Changes

Making Web Changes

Making Mobile Changes

Database Operations

View Database

Migrate & Seed

Reset Database

Troubleshooting

Stopping All Services