Observability and Debugging

End-to-end developer runbook

1. Step 1 - Confirm the API area: Identify the product area, route module, endpoint path, and consumer before writing or calling code.
2. Step 2 - Read the endpoint contract: Check method, auth, parameters, response, errors, side effects, and related docs.
3. Step 3 - Prepare authentication and input: Use the right session, bearer token, webhook secret, or internal header. Validate body and query data before sending it.
4. Step 4 - Make the request: Call the endpoint from the correct origin and environment. Keep credentials and secrets out of logs.
5. Step 5 - Verify response, side effects, and records: Confirm status code, response shape, database records, external side effects, and audit evidence.
6. Step 6 - Add tests, docs, and handoff notes: Update route inventory, consumer notes, and certification checks before depending on the change.

Debugging flow

1. Step 1 - Capture request metadata: Method, path, environment, request ID if present, actor type, and timestamp.
2. Step 2 - Avoid sensitive payload logs: Do not paste full attendee, payment, report, token, or secret data into logs or issues.
3. Step 3 - Reproduce with safe data: Use local or staging data where possible.
4. Step 4 - Inspect source handler: Check route module, middleware, bindings, and helper libraries.
5. Step 5 - Verify downstream systems: Supabase, Sanity, mail, Discord, Telegram, Google Wallet, GitHub, or deploy hooks may be the actual failure point.
6. Step 6 - Document resolution: Update route docs if the expected behavior was unclear.

Failure signals

1. Checkpoint 1 - CORS failure: Check origin configuration and credentials.
2. Checkpoint 2 - Auth failure: Check session family and role scope.
3. Checkpoint 3 - Validation failure: Check path, query, and body contract.
4. Checkpoint 4 - Side-effect failure: Check external service credentials and suppression flags.