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

# Local development quickstart

> Bring up the Handa Uncle backend on your laptop in under 10 minutes

<Info>
  The backend runs on Bun, connects to MongoDB + Redis, authenticates with
  Auth0, and calls OpenAI/Anthropic based on `AI_PROVIDER`. This guide walks
  through the minimum setup to exercise `/app/launch` and `/api/v1/auth/*`.
</Info>

## Requirements

| Tool         | Version | Notes                                                       |
| ------------ | ------- | ----------------------------------------------------------- |
| Bun          | 1.1+    | Used for the runtime and scripts (`bun install`, `bun dev`) |
| Node.js      | 20+     | Needed for some tooling (linting, VS Code extensions)       |
| pnpm         | 9+      | Optional, but matches the checked-in lockfile               |
| MongoDB      | 6.x     | Local Docker container or Atlas cluster                     |
| Redis        | 7.x     | Local container or Upstash credentials                      |
| Auth0 tenant | Any     | Populate the API + Management credentials                   |

## 1. Clone and install

```bash theme={null}
git clone https://github.com/handauncle/handauncle-backend-new.git
cd handauncle-backend-new
bun install
```

> Bun installs all workspaces declared in `package.json`, so the shared code
> under `src/shared` stays in sync with the service packages.

## 2. Configure environment variables

Copy the sample file and fill in the required keys:

```bash theme={null}
cp .env.example .env.development.local
```

Focus on these blocks (validated by `src/shared/config/env.schema.ts`):

| Group            | Required keys                                                                                                                              | Why                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| **Server & DB**  | `PORT`, `DATABASE_URL`                                                                                                                     | Bun boots on `PORT` (8080 in dev) and MongoDB connection string |
| **Redis**        | `REDIS_PROVIDER`, `REDIS_URL` *(or Upstash REST URL/token)*                                                                                | Rate limiting + caches                                          |
| **Auth0**        | `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`, `AUTH0_AUDIENCE`, `AUTH0_MANAGEMENT_CLIENT_ID`, `AUTH0_MANAGEMENT_CLIENT_SECRET` | JWT validation and management API calls                         |
| **AI providers** | `AI_PROVIDER`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`                                                                                       | Required depending on the provider you select                   |
| **RAG**          | `PINECONE_API_KEY`, `PINECONE_INDEX_NAME`, `SUPERMEMORY_API_KEY`, `RAG_ENABLED`                                                            | Knowledge retrieval and conversation memory                     |
| **Messaging**    | `EXOTEL_API_KEY`, `EXOTEL_API_TOKEN`, `EXOTEL_SID`, `EXOTEL_FROM_NUMBER`                                                                   | OTP delivery                                                    |

Keep secrets in your local environment (never commit). The schema will throw a
descriptive error if anything critical is missing.

## 3. Start dependencies

* **MongoDB / Redis**: run them locally (Docker, Atlas, Upstash). Update
  `DATABASE_URL` and the Redis section to point at the running instances.
* **External APIs**: ensure Auth0, Exotel, Langfuse, Pinecone credentials are
  valid for the environment you are targeting.

## 4. Run the server

```bash theme={null}
bun run dev
```

Open another terminal and hit the health checks:

```bash theme={null}
curl http://localhost:8080/api/v1/health
curl http://localhost:8080/app/health
```

Both responses should return `success: true`. The terminal logs will list the
mounted routes, request IDs, and any failing upstream calls.

## 5. Exercise core flows

<Steps>
  <Step title="Create or link a user">
    Use the scripts in `scripts/` (`create-test-user.ts`, `generate-test-token.ts`)
    to seed a MongoDB user tied to your Auth0 identity.
  </Step>

  <Step title="Send OTP / app launch">
    Hit `POST /api/v1/auth/send-otp` to verify the Exotel wiring, then call
    `GET /app/launch` with the headers defined in `/api-reference/endpoint/app-launch`.
  </Step>

  <Step title="Run the AI stack">
    Call `POST /api/v1/ai/chat` with a valid Bearer token and confirm traces appear
    in Langfuse.
  </Step>
</Steps>

## 6. Run tests and checks

| Command             | Purpose                                 |
| ------------------- | --------------------------------------- |
| `bun test`          | Runs the Bun-native unit tests          |
| `bun test --watch`  | Watches files for fast feedback         |
| `bun run typecheck` | Ensures the TypeScript project compiles |

## Next steps

* Follow the deeper workflow practices in `/development`
* Review `/api-reference/*` for the launch and system health contracts
* Read `APP_LAUNCH_IMPLEMENTATION.md` to understand how the device lookup +
  onboarding logic works before touching the service layer