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

# Full Stack Development

> Running all Soundcheck services together locally

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](https://docs.soundchecklive.io/engineering/development/environment-setup.md).

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

**1. Start shared infrastructure**

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

**2. Migrate and seed the database**

```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
```

**3. Start api-events**

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

Wait for health:

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

**4. Start the Web App**

In a new terminal:

```bash theme={null}
cd web && npm run dev:emulator
```

**5. Start the Mobile App**

In another terminal:

```bash theme={null}
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](http://localhost:3000) | Next.js dev server |
| api-events | [http://localhost:4000](http://localhost:4000) | Encore HTTP API (system of record) |
| Clerk emulator | [http://localhost:4711](http://localhost:4711) | Local auth personas |
| Database | localhost:5433 | PostgreSQL |

***

## Environment Configuration

Full per-component variables live in [Environment Setup](https://docs.soundchecklive.io/engineering/development/environment-setup.md). 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](https://docs.soundchecklive.io/engineering/development/environment-setup.md#physical-device-on-a-different-vlan)).
* **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`.

> [!WARNING]
>
> 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

```bash theme={null}
psql -h localhost -p 5433 -U postgres -d soundcheck
```

### Migrate & Seed

```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:baseline    # minimal roles/plans
npm run db:seed:demo-full   # demo org + Clerk personas
```

### Reset Database

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

> [accordion] api-events can't connect to database
>
> Ensure shared infra is running:
>
> ```bash theme={null}
> npm run dev:infra
> docker compose -p api -f dev/docker-compose.yml ps
> ```

> [accordion] Web app can't reach API
>
> 1. Check api-events is running: `curl http://localhost:4000/health`
> 2. Verify `BACKEND_API_URL=http://localhost:4000` in `web/.env.local`
> 3. Clear `.next/` after changing `NEXT_PUBLIC_*` vars

> [accordion] Mobile app can't reach API
>
> 1. Use your computer's IP instead of `localhost`
> 2. Ensure phone/emulator is on same network
> 3. Check firewall settings

> [accordion] Port already in use
>
> ```bash theme={null}
> lsof -ti:4000 | xargs kill -9   # api-events
> lsof -ti:3000 | xargs kill -9   # web
> ```

> [accordion] Authentication issues
>
> Ensure all services use the same Clerk credentials (or the local emulator via `npm run dev:emulator` launchers).

***

## Stopping All Services

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


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