Quick Start

Get the Soundcheck platform running locally with this quick start guide.

Choose your component

Mobile App

React Native development

Web App

Next.js development

API (api-events)

Encore.ts backend

Full Stack

Run everything together

Mobile app

Clone the repository

git clone <repository-url>
cd soundcheck-mobile-app

Install dependencies

npm install

Set up environment variables

cp .env.example .env

Add your Clerk publishable key to .env:

EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_key_here
EXPO_PUBLIC_API_URL=http://localhost:4000

Start the development server

npm start

Press i for iOS simulator or a for Android emulator.

Web app

Navigate to web directory

cd web

Install dependencies

npm install

Set up environment variables

cp .env.example .env.local

Configure your .env.local:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_key
CLERK_SECRET_KEY=your_clerk_secret
NEXT_PUBLIC_API_URL=/api-proxy/api/v1
BACKEND_API_URL=http://localhost:4000

Start the development server

Prefer the emulator launcher (shared infra + Encore on :4000):

npm run dev:emulator

Or plain npm run dev after you start api-events yourself. Open http://localhost:3000

api-events

Start shared infrastructure

From the repo root:

npm run dev:infra

Brings up Postgres (:5433), Clerk emulator (:4711), and Azurite.

Migrate and seed

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

Run api-events

cd api-events && npm run dev:emulator

Verify it's running

API: http://localhost:4000
Health: http://localhost:4000/health

Full stack

Run all components together for full-stack development:

Start shared infrastructure

npm run dev:infra
cd api-events && npm run db:migrate && npm run db:seed:demo-full

Start api-events

In a new terminal:

cd api-events && npm run dev:emulator

Start the Web App

In another 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
Web App	http://localhost:3000
api-events	http://localhost:4000
Clerk emulator	http://localhost:4711
Database	localhost:5433

Dev container (recommended)

The easiest way to get started is using a Dev Container, which provides a pre-configured development environment.

Install the Dev Containers extension

VS Code: Install Dev Containers extension
Cursor: Install the same extension from the Extensions panel

Open in Dev Container

Open the project folder in VS Code/Cursor
Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
Select “Dev Containers: Reopen in Container”

Start developing

The container automatically installs dependencies and configures the environment.

npm run dev:infra
cd api-events && npm run dev:emulator

Dev Containers run in Docker, so you cannot connect physical devices directly via USB. Use npm run web to test in a browser, or Expo Go on your device (connected to the same network).

Next steps

Key Concepts

Understand Soundcheck fundamentals

Platform tour

Explore the platform features

Environment Setup

Configure your development environment

Troubleshooting

Common issues and solutions

Overview

Backend

Backend integrations

API reference

Frontend

Mobile

Infrastructure

CI/CD

Development

Guides

Reference

Choose your component

Mobile App

Web App

API (api-events)

Full Stack

Mobile app

Web app

api-events

Full stack

Access points

Dev container (recommended)

Next steps

Key Concepts

Platform tour

Environment Setup

Troubleshooting

​Choose your component

Mobile App

Web App

API (api-events)

Full Stack

​Mobile app

​Web app

​api-events

​Full stack

​Access points

​Dev container (recommended)

​Next steps

Key Concepts

Platform tour

Environment Setup

Troubleshooting

Choose your component

Mobile app

Web app

api-events

Full stack

Access points

Dev container (recommended)

Next steps