Skip to main content

Support & Runbook (Internal)

Purpose​

This document is the primary runbook for support engineers handling user issues, triage, and escalations.

Access & Tools​

  • Supabase Console (for inspecting rows and auth).
  • Logs: hosting provider logs for backend-sync and mobile analytics.
  • Local dev: ability to run backend-sync locally and reproduce parsers with sample emails.

Onboarding Checklist for Support​

  1. Access to Supabase project and read-only keys.
  2. Access to logging/host provider dashboard.
  3. Slack channel or pager for on-call alerts.

Common Issues & Steps​

  • Missing trips:

    1. Check Supabase trips for the user id.
    2. Check backend-sync logs for recent parse jobs.
    3. Confirm user's email ingestion permissions and whether the raw email exists.

  • Transaction parsing errors:

    1. Pull the raw_text from transactions if present.
    2. Run the finance parser locally with the raw text fixture.
    3. If reproducible, open a PR with fixes to backend-sync/services/financeProcessor.ts and add unit tests.

  • Authentication problems:

    1. Verify Supabase auth session tokens; check lib/supabase.ts configuration.
    2. Inspect device logs for AsyncStorage issues.

Reproducing Issues Locally​

  1. Checkout the repo and run:
cd backend-sync
yarn install
yarn dev
  1. Use provided fixtures (create a test JSON file with the raw email) and call local endpoints or run the parser directly.

Diagnostics & Useful Queries​

  • Supabase: query select * from trips where user_id = '...' order by created_at desc.
  • Backend logs: search for parser errors or exceptions with user identifiers.

Escalation Path​

  1. If the issue is reproducible and appears to be a parser bug, create an issue in the repo and assign backend owner.
  2. If the issue is infra (Supabase or hosting outage), alert the on-call infra engineer.
  3. For data breaches or sensitive incidents, follow the security incident response plan and notify product/security immediately.

Release & Rollback Notes​

  • Check semantic-release configuration and deployment logs when investigating post-release regressions.
  • If a backend deploy causes failures, rollback via the host provider or redeploy the previous working version.

Add detailed playbooks for additional recurring issues as they appear.