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

cd stitch/frontend
npm install

Start the frontend in development mode:

npm run dev

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

Install the Backend

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

Start the API locally:

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:

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:

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.

Optional Local Infrastructure

LiveKit

Run a local LiveKit server for voice and video features:

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

Gorse Recommendation Stack

Run the local recommendation stack:

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:

cd stitch/frontend
npm run lint

cd stitch/backend
pytest

Build the Documentation Site

From the repository root:

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.