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

# Handa Uncle Platform

> Architecture, operations, and API guides for the Handa Uncle wealth assistant

<Note>
  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`.
</Note>

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

<Columns cols={3}>
  <Card title="Local development" icon="rocket" href="/quickstart">
    Spin up the Bun server, seed MongoDB, and validate health checks in minutes.
  </Card>

  <Card title="Contributor workflow" icon="screwdriver-wrench" href="/development">
    Coding standards, branch expectations, and how we run tests/type checks.
  </Card>

  <Card title="Mobile app bootstrap" icon="mobile" href="/api-reference/endpoint/app-launch">
    Contract for `/app/launch`, including device headers, onboarding signals, and usage stats.
  </Card>
</Columns>

## Codebase guides

<CardGroup cols={3}>
  <Card title="Architecture overview" icon="sitemap" href="/codebase/architecture">
    Runtime stack, shared configs, and how the Hono/Bun server boots and stays healthy.
  </Card>

  <Card title="Service catalog" icon="list-check" href="/codebase/service-catalog">
    Responsibilities for every `src/services/*` module plus the supporting packages.
  </Card>

  <Card title="Core workflows" icon="diagram-project" href="/codebase/core-workflows">
    Step-by-step references for chat orchestration, RAG, app launch, files, and shares.
  </Card>
</CardGroup>

## Where to go next

<CardGroup cols={2}>
  <Card title="Architecture notes" icon="diagram-project" href="https://github.com/handauncle/handauncle-backend-new/blob/main/IMPLEMENTATION_SUMMARY.md">
    Deep dives on authentication adapters, OTP orchestration, and rollout plans.
  </Card>

  <Card title="Mobile API playbook" icon="mobile-screen-button" href="https://github.com/handauncle/handauncle-backend-new/blob/main/MOBILE_API_ENDPOINTS.md">
    End-to-end examples for Google login, refresh, logout, and app launch flows.
  </Card>

  <Card title="Environment reference" icon="gear" href="/codebase/settings">
    Validated list of environment variables enforced by `env.schema.ts`.
  </Card>

  <Card title="API reference" icon="terminal" href="/api-reference/introduction">
    Interactive OpenAPI playground for the launch and health endpoints.
  </Card>
</CardGroup>

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