# Getting Started

This section walks through the local developer setup for the current repository layout.

## Prerequisites

- `Node.js` 20 or newer and `npm`
- `Python` 3.13 or newer
- Access to a Supabase project with the Sejong Pulse schema applied
- Optional external service credentials for features such as Sendbird, Cloudinary, Algolia, LiveKit, OpenRouter, and billing
- `Docker` if you want to run the local Gorse or LiveKit stacks

## Install the Frontend

```bash
cd stitch/frontend
npm install
```

Start the frontend in development mode:

```bash
npm run dev
```

The frontend expects the API at `http://localhost:8000/api` by default.

## Install the Backend

```bash
cd stitch/backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Start the API locally:

```bash
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

The deployed Render command uses `stitch/backend/scripts/start_api.sh`, which starts the same app on `${PORT:-10000}`.

## Minimum Environment Variables

### Frontend

Set these in your frontend environment, for example in `.env.local`:

```bash
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api
NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
```

### Backend

Set these in the backend environment before starting FastAPI:

```bash
SUPABASE_URL=your-supabase-url
SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key
CORS_ALLOW_ORIGINS=http://localhost:3000
FRONTEND_APP_URL=http://localhost:3000
OPENAI_API_KEY=your-openrouter-or-openai-compatible-key
```

Additional service-specific variables are documented in the [Configuration Guide](configuration-guide.md).

## Optional Local Infrastructure

### LiveKit

Run a local LiveKit server for voice and video features:

```bash
docker compose -f stitch/docker-compose.livekit.yml up
```

### Gorse Recommendation Stack

Run the local recommendation stack:

```bash
docker compose -f stitch/docker-compose.gorse.yml up
```

## Database and Schema

- The canonical schema snapshot lives in `stitch/backend/supabase_schema.sql`.
- Incremental SQL changes live in `stitch/backend/migrations`.

## Verification Commands

Run these checks before sharing changes:

```bash
cd stitch/frontend
npm run lint
```

```bash
cd stitch/backend
pytest
```

## Build the Documentation Site

From the repository root:

```bash
cd docs
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
make html
```

The generated site will be written to `docs/_build/html`.