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

cd stitch/frontend
npm run lint

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