# Configuration Guide

Sejong Pulse uses environment variables across the frontend, backend, workers, and deployment layers. This page summarizes the main variables already referenced in the repository.

## Frontend Variables

The frontend centralizes its public runtime settings in `stitch/frontend/src/lib/config.ts`.

| Variable | Purpose |
| --- | --- |
| `NEXT_PUBLIC_API_BASE_URL` | Base URL for backend API requests |
| `NEXT_PUBLIC_SUPABASE_URL` | Supabase project URL |
| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Public Supabase client key |
| `NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME` | Cloudinary cloud identifier for client uploads |
| `NEXT_PUBLIC_SENDBIRD_APP_ID` | Sendbird application identifier |
| `NEXT_PUBLIC_ALGOLIA_APP_ID` | Algolia application identifier |
| `NEXT_PUBLIC_ALGOLIA_SEARCH_KEY` | Search-only Algolia key |

## Core Backend Variables

These are required or commonly used in `stitch/backend/main.py`.

| Variable | Purpose |
| --- | --- |
| `SUPABASE_URL` | Supabase project URL |
| `SUPABASE_ANON_KEY` | Backend-side anon key for user-scoped actions |
| `SUPABASE_SERVICE_ROLE_KEY` | Service-role key for privileged backend operations |
| `CORS_ALLOW_ORIGINS` | Comma-separated allowed origins |
| `FRONTEND_APP_URL` | Canonical frontend URL used in callbacks and emails |
| `OPENAI_API_KEY` or `OPENROUTER_API_KEY` | AI provider key for advisor requests |
| `OPENAI_API_BASE_URL` | OpenAI-compatible base URL, defaulting to OpenRouter |
| `AI_HTTP_REFERER` | Referrer sent to the AI provider |
| `AI_APP_TITLE` | Display title sent to the AI provider |
| `SENTRY_DSN` | Error tracking configuration |

## Search, Media, and Messaging

| Variable | Purpose |
| --- | --- |
| `ALGOLIA_APP_ID` | Algolia application identifier |
| `ALGOLIA_WRITE_API_KEY` | Algolia write key for indexing |
| `ALGOLIA_SEARCH_API_KEY` | Optional search-only key for backend search calls |
| `ALGOLIA_PULSES_INDEX` | Pulse index name, default `pulses` |
| `CLOUDINARY_CLOUD_NAME` | Cloudinary cloud name |
| `CLOUDINARY_API_KEY` | Cloudinary API key |
| `CLOUDINARY_API_SECRET` | Cloudinary API secret |
| `SENDBIRD_APP_ID` | Sendbird app identifier |
| `SENDBIRD_API_KEY` | Sendbird server API token |
| `SENDBIRD_API_URL` | Optional override for the Sendbird API base URL |

## Realtime and Recommendation Services

| Variable | Purpose |
| --- | --- |
| `LIVEKIT_URL` | LiveKit websocket URL |
| `LIVEKIT_API_KEY` | LiveKit API key |
| `LIVEKIT_API_SECRET` | LiveKit API secret |
| `LIVEKIT_DEV_MODE` | Enables local LiveKit defaults when `true` |
| `REDIS_URL` | Redis connection string for cache and workers |
| `REDIS_KEY_PREFIX` | Namespace prefix for cache and job keys |
| `GORSE_ENDPOINT` or `GORSE_ADDRESS` | Gorse API endpoint |
| `GORSE_API_KEY` | Gorse server API key |
| `GORSE_DISCOVERY_CATEGORY` | Category name used for discovery recommendations |
| `GORSE_PULSE_CATEGORY` | Category name used for pulse recommendations |
| `GORSE_TIMEOUT_SECONDS` | Timeout for recommendation calls |

## Billing and Email

| Variable | Purpose |
| --- | --- |
| `SENDGRID_API_KEY` | SendGrid API token |
| `SENDGRID_FROM_EMAIL` | Sender address for transactional email |
| `STRIPE_SECRET_KEY` | Backend secret for billing provider integration |
| `STRIPE_WEBHOOK_SECRET` | Webhook signature verification |
| `STRIPE_PRICE_ID` | Subscription price identifier |
| `TOSS_PAYMENTS_API_BASE_URL` | Toss billing API base URL |
| `TOSS_PAYMENTS_CLIENT_KEY` | Toss client key |
| `TOSS_PAYMENTS_SECRET_KEY` | Toss server secret |
| `TOSS_PAYMENTS_WEBHOOK_URL_SECRET` | Secret used for webhook validation |
| `BILLING_INTERNAL_JOB_SECRET` | Secret for internal renewal job calls |
| `BILLING_TIMEZONE` | Billing timezone, currently `Asia/Seoul` in deployment config |

## Worker and Queue Controls

| Variable | Purpose |
| --- | --- |
| `BACKGROUND_JOBS_INLINE` | Run background jobs inline instead of durably |
| `BACKGROUND_JOB_MAX_WORKERS` | Max local background worker count |
| `JOB_QUEUE_PROCESSING_TIMEOUT_SECONDS` | Timeout for job processing |
| `JOB_QUEUE_MAX_ATTEMPTS` | Retry count for jobs |
| `RECOMMENDATION_OUTBOX_BATCH_SIZE` | Batch size for recommendation outbox processing |
| `RECOMMENDATION_OUTBOX_IDLE_SLEEP_SECONDS` | Idle sleep time for the recommendation worker |

## Authentication and Identity

| Variable | Purpose |
| --- | --- |
| `SEJONG_AUTH_INTERNAL_EMAIL_DOMAIN` | Internal email domain used for Sejong-to-Supabase account bootstrap |

## Deployment Files

- `stitch/render.yaml` documents the current backend, worker, and cron configuration.
- `stitch/frontend/netlify.toml` documents frontend deployment behavior on Netlify.

## Recommended Approach

1. Keep public variables in the frontend environment only when the browser truly needs them.
2. Keep provider secrets on the backend or deployment platform.
3. Start with the minimum Supabase and API variables, then layer in integrations one by one.
4. Treat recommendation, messaging, billing, and call features as optional until their credentials are configured.