Skip to main content
The Handa Uncle backend powers the consumer mobile app, AI/insights features, and operational tooling. These docs complement the in-repo design notes such as IMPLEMENTATION_SUMMARY.md, APP_LAUNCH_IMPLEMENTATION.md, and MOBILE_API_ENDPOINTS.md.

​
Platform at a glance

  • Channels – /api/v1/* is the authenticated public API, /app/* is the lightweight bootstrap flow for mobile installs, and /api/webhooks/* ingests Langfuse + prompt updates.
  • Core services – Auth (Auth0 adapter, OTP, device binding), AI/RAG (OpenAI/Anthropic orchestration, Pinecone + Supermemory), Profile/Context stores (MongoDB + Redis), and App launch orchestration.
  • Observability – Langfuse traces every AI request, request IDs are added to all responses, and structured logs stream to the terminal + Cloud Logging.

​
Service map

Local development

Spin up the Bun server, seed MongoDB, and validate health checks in minutes.

Contributor workflow

Coding standards, branch expectations, and how we run tests/type checks.

Mobile app bootstrap

Contract for /app/launch, including device headers, onboarding signals, and usage stats.

​
Codebase guides

Architecture overview

Runtime stack, shared configs, and how the Hono/Bun server boots and stays healthy.

Service catalog

Responsibilities for every src/services/* module plus the supporting packages.

Core workflows

Step-by-step references for chat orchestration, RAG, app launch, files, and shares.

​
Where to go next

Architecture notes

Deep dives on authentication adapters, OTP orchestration, and rollout plans.

Mobile API playbook

End-to-end examples for Google login, refresh, logout, and app launch flows.

Environment reference

Validated list of environment variables enforced by env.schema.ts.

API reference

Interactive OpenAPI playground for the launch and health endpoints.

​
Operational checklist

  • Track every request with X-Request-ID and keep a log of failing IDs in incidents.
  • Keep MongoDB and Redis running locally (the app launch path exercises both).
  • For AI regressions, replay the failing Langfuse trace with the same prompt label (LANGFUSE_PROMPT_LABEL) before shipping fixes.
  • Prefer small, incremental doc updates—link to the source files in /src whenever describing behavior.