Skip to main content

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.

Cursor is our primary editor for navigating the Bun monorepo, updating services, and editing these docs. Configure it once so every engineer (and AI assistant) shares the same guardrails.

​
1. Project rules

mkdir -p .cursor
./.cursor/rules.md: 
# Handa Uncle backend

- Stack: Bun + Hono server, MongoDB, Redis, Auth0, Pinecone, Langfuse.
- Never delete user code unless asked. Prefer minimal diffs.
- Cite exact files (e.g. `src/services/app/services/app-launch.service.ts`).

## Critical invariants

1. `/app/launch` requires `x-device-id` + `x-platform` headers.
2. OTP flow uses Exotel with retries defined in `otp.service.ts`.
3. Rate limiting + request metadata live under `src/shared/middlewares/`.
4. Documentation must align with `docs/api-reference/openapi.json`.

## Workflow

- Run `git status` before editing and summarize existing changes.
- Use Bun for scripts/tests: `bun run dev`, `bun run typecheck`, `bun test`.
- Keep `X-Request-ID` in all new logs.
- Update MDX pages + `docs.json` together so navigation stays valid.

## Language

- Write instructions in second person.
- Include verification steps (curl response, log snippet, etc.).
- Keep tone concise and technical—this is an internal engineering audience.
Restart Cursor or reload the workspace so the new rules are applied.

​
2. Command palette shortcuts

CommandWhen to run
bun run devBoot the API on http://localhost:8080
bun run typecheckBefore every commit/PR
bun test --watchIterate on service logic
mint dev --port 3334Preview the Mintlify docs
Add them to Cursor’s “Custom Commands” so they’re one keystroke away.

​
3. Supplying context to AI

When Cursor asks for more information:
  • Point it to APP_LAUNCH_IMPLEMENTATION.md for device boot flow context.
  • Use MOBILE_API_ENDPOINTS.md when editing auth/app contracts.
  • Link docs/api-reference/openapi.json whenever modifying API responses.
  • Reference the exact service/controller file instead of paraphrasing.

​
4. Things to avoid

  • Don’t touch .env.* files or rotate secrets from within Cursor.
  • Don’t run destructive git commands (reset --hard, clean -fd) without explicit approval.
  • Don’t invent API payloads—copy from the code, tests, or Langfuse traces.