> ## Documentation Index
> Fetch the complete documentation index at: https://docs.handauncle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer workflow

> Standards for contributing to the Handa Uncle backend

## 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

| Task              | Command              | Notes                                                   |
| ----------------- | -------------------- | ------------------------------------------------------- |
| Start API locally | `bun run dev`        | Runs `server.ts` with watch mode and logs every request |
| Type checking     | `bun run typecheck`  | Uses `tsc --noEmit`; required before every PR           |
| Unit tests        | `bun test`           | Bun-native test runner, respects `.test.ts` files       |
| Watch tests       | `bun test --watch`   | Great for iterating on services like OTP + launch       |
| Build             | `bun run build:full` | Type check + Bun build (used by CI)                     |

## Coding standards

<AccordionGroup>
  <Accordion title="Logging & tracing">
    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.
  </Accordion>

  <Accordion title="Error handling">
    Throw domain-specific errors from `src/shared/utils/errors.ts`. Controllers
    call `successResponse`/`errorResponse` so the envelope stays consistent across
    `/api/v1/*` and `/app/*`.
  </Accordion>

  <Accordion title="Schema-first APIs">
    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.
  </Accordion>
</AccordionGroup>

## 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

<Check>
  All items must be true before requesting review.
</Check>

* [ ] 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

| Symptom                                 | Fix                                                                                                   |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `Environment validation failed` on boot | Double-check `.env.development.local`; the console prints the missing field                           |
| Redis errors on startup                 | Ensure `REDIS_PROVIDER` aligns with the fields you set (`redis` vs `upstash`)                         |
| Auth0 401s locally                      | Verify `AUTH0_AUDIENCE` matches the API identifier configured in Auth0                                |
| OTP SMS fails with 401                  | Confirm Exotel credentials (API key/token/SID) and the region-specific subdomain                      |
| Langfuse traces missing                 | Set `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, and `LANGFUSE_HOST`, or disable tracing temporarily |