# Maintenance and Troubleshooting

This page focuses on the recurring operational tasks that keep Sejong Pulse healthy and the first checks to run when a feature is failing.

## Routine Maintenance

### Run Quality Checks

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

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

### Verify Health Endpoints

- Check `/api/health` for backend health.
- Check `/api/recommendation/health` for recommendation status.

### Keep Recommendation Data Fresh

The repository includes:

- `stitch/backend/recommendation_worker.py` for draining recommendation events
- `stitch/backend/scripts/backfill_gorse.py` for backfill and sync
- `stitch/backend/scripts/run_gorse_backfill.sh` for cron execution

If recommendations look stale, verify Gorse connectivity and run a backfill.

### Refresh Knowledge Assets

When academic data changes:

1. Update the source files in `stitch/backend/knowledge`.
2. Run `stitch/backend/extract_knowledge.py` if the spreadsheet source changed.
3. Run `stitch/backend/ingest_knowledge.py` to rebuild the index.

### Review Deployment Config

- `Render` services and workers are defined in `stitch/render.yaml`.
- `Netlify` behavior is defined in `stitch/frontend/netlify.toml`.

## Common Issues

### The frontend loads but API calls fail

Check:

- `NEXT_PUBLIC_API_BASE_URL`
- `CORS_ALLOW_ORIGINS`
- whether the backend is actually listening on `localhost:8000` in local development

### Sejong sign-in works inconsistently

Check:

- Sejong authentication availability
- `SUPABASE_URL`, `SUPABASE_ANON_KEY`, and `SUPABASE_SERVICE_ROLE_KEY`
- the internal email bootstrap configuration controlled by `SEJONG_AUTH_INTERNAL_EMAIL_DOMAIN`

### Search returns empty results

Check:

- `ALGOLIA_APP_ID`
- search and write keys
- whether pulse indexing is succeeding after create and delete operations

### Calls or voice sessions do not start

Check:

- `LIVEKIT_URL`
- `LIVEKIT_API_KEY`
- `LIVEKIT_API_SECRET`
- whether the local or deployed LiveKit service is reachable

### Recommendations look empty or outdated

Check:

- `GORSE_ENDPOINT`
- `GORSE_API_KEY`
- `REDIS_URL`
- whether the recommendation worker and cron backfill are running

### Chat or advisor features fail

Check:

- `OPENAI_API_KEY` or `OPENROUTER_API_KEY`
- `OPENAI_API_BASE_URL`
- quota or rate-limit errors in backend logs

### Documentation build fails

Check:

- that `docs/requirements.txt` is installed in the active virtual environment
- that you are running `make html` from the `docs` directory

## Logging and Observability

The backend initializes structured JSON logging and optional Sentry monitoring. When debugging production issues, start with:

1. Render service logs for the API or workers
2. Netlify deploy logs for frontend build issues
3. Sentry traces and exceptions when configured