Skip to main content
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

ToolVersionNotes
Bun1.1+Used for the runtime and scripts (bun install, bun dev)
Node.js20+Needed for some tooling (linting, VS Code extensions)
pnpm9+Optional, but matches the checked-in lockfile
MongoDB6.xLocal Docker container or Atlas cluster
Redis7.xLocal container or Upstash credentials
Auth0 tenantAnyPopulate 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):
GroupRequired keysWhy
Server & DBPORT, DATABASE_URLBun boots on PORT (8080 in dev) and MongoDB connection string
RedisREDIS_PROVIDER, REDIS_URL (or Upstash REST URL/token)Rate limiting + caches
Auth0AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_AUDIENCE, AUTH0_MANAGEMENT_CLIENT_ID, AUTH0_MANAGEMENT_CLIENT_SECRETJWT validation and management API calls
AI providersAI_PROVIDER, OPENAI_API_KEY, ANTHROPIC_API_KEYRequired depending on the provider you select
RAGPINECONE_API_KEY, PINECONE_INDEX_NAME, SUPERMEMORY_API_KEY, RAG_ENABLEDKnowledge retrieval and conversation memory
MessagingEXOTEL_API_KEY, EXOTEL_API_TOKEN, EXOTEL_SID, EXOTEL_FROM_NUMBEROTP 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

1

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

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

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

CommandPurpose
bun testRuns the Bun-native unit tests
bun test --watchWatches files for fast feedback
bun run typecheckEnsures 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