Skip to main content

​
Branch + dependency conventions

  • Prefix feature branches with the corresponding workstream, e.g. apimigration/app-launch-docs.
  • Use Bun for scripts/tests (bun install, bun run dev). pnpm is still supported for dependency audits, but Bun is the source of truth.
  • Keep workspaces aligned: if you change src/shared/, run bun run typecheck from the repo root so all services compile.

​
Core commands

TaskCommandNotes
Start API locallybun run devRuns server.ts with watch mode and logs every request
Type checkingbun run typecheckUses tsc --noEmit; required before every PR
Unit testsbun testBun-native test runner, respects .test.ts files
Watch testsbun test --watchGreat for iterating on services like OTP + launch
Buildbun run build:fullType check + Bun build (used by CI)

​
Coding standards

Always log with logger from src/shared/utils/logger.ts. Include requestId (available via BaseController.getRequestId) and contextual identifiers such as phone, device, or user IDs. Langfuse spans should reuse the same IDs.
Throw domain-specific errors from src/shared/utils/errors.ts. Controllers call successResponse/errorResponse so the envelope stays consistent across /api/v1/* and /app/*.
Validate external input with Zod (see env.schema.ts and auth schemas). Update the OpenAPI file under docs/api-reference whenever you change the request contract or response shape.

​
Docs + design notes

  • Update the relevant markdown file at the repo root (APP_LAUNCH_IMPLEMENTATION.md, MOBILE_API_ENDPOINTS.md, etc.) whenever behavior changes.
  • The Mintlify docs live in /docs. Preview locally with mint dev --port 3334 (keep it different from the Bun server on 8080).

​
Pull request checklist

All items must be true before requesting review.
  • TypeScript compiles (bun run typecheck)
  • Tests relevant to the change pass (bun test or targeted bun test path)
  • Env schema updates documented in /docs/essentials/settings
  • OpenAPI + MDX docs updated if the API contract moved
  • Logs include enough context to debug from X-Request-ID
  • Screenshot of new docs sections (if applicable) attached to the PR

​
Troubleshooting

SymptomFix
Environment validation failed on bootDouble-check .env.development.local; the console prints the missing field
Redis errors on startupEnsure REDIS_PROVIDER aligns with the fields you set (redis vs upstash)
Auth0 401s locallyVerify AUTH0_AUDIENCE matches the API identifier configured in Auth0
OTP SMS fails with 401Confirm Exotel credentials (API key/token/SID) and the region-specific subdomain
Langfuse traces missingSet LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and LANGFUSE_HOST, or disable tracing temporarily