Local development quickstart

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/*.

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

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:

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

bun run dev

Open another terminal and hit the health checks:

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

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.

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.

Run the AI stack

Call POST /api/v1/ai/chat with a valid Bearer token and confirm traces appear in Langfuse.

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

Overview

Contributing

Codebase

AI Tools

Practices

Requirements

1. Clone and install

2. Configure environment variables

3. Start dependencies

4. Run the server

5. Exercise core flows

6. Run tests and checks

Next steps

​Requirements

​1. Clone and install

​2. Configure environment variables

​3. Start dependencies

​4. Run the server

​5. Exercise core flows

​6. Run tests and checks

​Next steps

Requirements

1. Clone and install

2. Configure environment variables

3. Start dependencies

4. Run the server

5. Exercise core flows

6. Run tests and checks

Next steps