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

# Web App Overview

> Next.js web application for Soundcheck

Soundcheck Web is the desktop platform for managing live music events, built with Next.js 16.3 and React 19.

For upgrade notes and the residual migration checklist, see [Next.js 16 Upgrade Notes](https://docs.soundchecklive.io/engineering/frontend/nextjs-16-upgrade.md).

## Features

### Core functionality

| Feature | Description |
| - | - |
| **Event Management** | Create, manage, and track live music events |
| **Setlist Builder** | Build and organize performance setlists with drag-and-drop |
| **Team Collaboration** | Manage team members, roles, and permissions |
| **Lead Management** | Track and convert leads into events |
| **Multi-Organization** | Support for multiple organizations per user |
| **Public Profiles** | Public-facing organization and user profiles |
| **Real-time Updates** | SWR-powered data fetching with automatic revalidation |

***

## Technology stack

### Core technologies

| Technology | Version | Purpose |
| - | - | - |
| Next.js | 16.3.0 | React framework (App Router) |
| React | 19 | UI library |
| TypeScript | 7.0.2 (`tsc`); `@typescript/typescript6` for AST guard test only | Type-safe development |
| Tailwind CSS | 4.3.0 | Styling |

### Data and state

| Technology | Purpose |
| - | - |
| SWR 2.3.0 | Server state management |
| React Context | Global state |
| Formik + Yup | Form management |
| Axios | HTTP client |

### UI components

| Library | Purpose |
| - | - |
| Radix UI | Accessible primitives |
| Shadcn/ui | Component library |
| Lucide React | Icons (primary) |
| Framer Motion | Animations |

### Authentication

| Service | Purpose |
| - | - |
| Clerk | User authentication |
| @clerk/nextjs | Next.js integration |

***

## Project structure

```
web/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── (app)/             # Protected routes (requires auth)
│   │   │   ├── dashboard/     # Dashboard page
│   │   │   ├── gigs/          # Event/gig management
│   │   │   ├── setlist/       # Setlist management
│   │   │   ├── leads/         # Lead management
│   │   │   ├── teams/         # Team management
│   │   │   └── layout.tsx     # App layout
│   │   ├── api/               # API routes
│   │   └── sign-in/           # Public auth pages
│   ├── components/
│   │   ├── ui/                # Shadcn/ui primitives
│   │   ├── common/            # Shared business components
│   │   └── static/            # Layout components
│   ├── lib/
│   │   ├── context/           # React Context providers
│   │   ├── hooks/             # Custom React hooks
│   │   ├── services/          # API service layer
│   │   └── types/             # TypeScript types
│   └── assets/
│       ├── new-icons/         # SVG icons
│       └── images/            # Image assets
├── automated-tests/           # Playwright E2E tests
├── docker/                    # Docker configuration
└── package.json
```

***

## Development commands

### Core commands

```bash theme={null}
cd web

npm install     # Install dependencies
npm run dev     # Start development server (port 3000)
npm run build   # Build for production
npm run start   # Start production server
```

### Quality checks

```bash theme={null}
npm run lint       # Run oxlint
npm run typecheck  # TypeScript type checking
```

### Testing

```bash theme={null}
npm test          # Run Vitest unit tests (web)
npm run test:e2e  # Run Playwright E2E tests
npm run test:e2e-ui   # Playwright with UI mode
npm run test:e2e-d    # Playwright debug mode
```

***

## Environment variables

Create `.env.local` in the `web/` directory:

```env theme={null}
# Authentication (Required)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# API (Required — local dev proxy avoids CORS issues)
NEXT_PUBLIC_API_URL=/api-proxy/api/v1
BACKEND_API_URL=http://localhost:4000

# Optional
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=...
NEXT_PUBLIC_GTM_ID=...
```

***

## Docker

### Build image

```bash theme={null}
docker build -t soundcheck-web . --network host \
  --build-arg NEXT_PUBLIC_API_URL=xxx \
  --build-arg NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=xxx \
  --build-arg CLERK_SECRET_KEY=xxx
```

### Run image

```bash theme={null}
docker run -p 3000:3000 soundcheck-web
```

***

## Next steps

> [card] [Setup Guide](https://docs.soundchecklive.io/engineering/frontend/setup.md)
>
> Local development setup

> [card] [Architecture](https://docs.soundchecklive.io/engineering/frontend/architecture.md)
>
> Detailed architecture documentation

> [card] [Testing](https://docs.soundchecklive.io/engineering/frontend/testing.md)
>
> Testing strategies

> [card] [Full Stack](https://docs.soundchecklive.io/engineering/guides/full-stack-development.md)
>
> Run with api-events locally


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