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

# Core backend workflows

> Step-by-step references for the paths every Handa Uncle developer touches.

<Note>
  These walkthroughs map directly to the production code so you can jump from
  “what happens?” to “where is it implemented?” without chasing Slack threads.
</Note>

## Authenticated API call

<Steps>
  <Step title="Request enters Hono">
    `server.ts` applies `hono/logger`, CORS, and the request-ID middleware before
    your handler runs. The UUID is stored in `c.get('requestId')` and appended to
    every `successResponse`/`errorResponse`.
  </Step>

  <Step title="Authentication & context">
    `auth0JwtMiddleware` verifies the RS256 JWT using Auth0’s JWKS, looks up (or
    auto-creates) the Mongo user via `userRepository`, and injects `userId`,
    `roles`, `permissions`, and the raw payload into the request context. Routes
    that accept anonymous traffic use `optionalAuth0JwtMiddleware`.
  </Step>

  <Step title="Controller execution">
    Controllers inherit from `BaseController` to read the request ID, unwrap
    headers, and return typed responses. Errors bubble into
    `errorHandlerMiddleware`, which standardizes the envelope and logs with the
    same context.
  </Step>
</Steps>

## Chat orchestration & memory

<Steps>
  <Step title="Conversation bootstrap">
    `ChatOrchestrationService.processChat`/`processStreamingChat` find or create
    a conversation via `ConversationRepository`, persist the user message (plus
    attachments), and schedule background title generation. When creating a new
    conversation, the service automatically stores metadata including the
    pre-prompt key (if used) and input type (`text`, `file`, or `voice` based
    on whether attachments are present).
  </Step>

  <Step title="Context hydration">
    The service resolves preprompts (`prePromptService`), loads prior messages,
    merges SuperMemory context via `MemoryService`, and stitches inline/remote
    attachments using `file-attachment.helper.ts`. The resolved pre-prompt's
    masked value is injected into the conversation while the public key is
    stored in the conversation document for analytics.
  </Step>

  <Step title="LLM call + tracking">
    `llmService` fans out to the configured provider, Langfuse spans are emitted
    (thanks to `instrumentation.ts`), and `usageTrackingService` increments the
    user's quota. Assistant messages are saved back through
    `MessageRepository`, ensuring transcripts stay consistent with the
    Conversations API.
  </Step>
</Steps>

## Retrieval-augmented answers

<Steps>
  <Step title="Query planning">
    The RAG controller receives the user query, normalizes filters, and calls
    the query generator (`services/ai/services/query-generator.service.ts`) to
    determine intent and required tools.
  </Step>

  <Step title="Vector + memory fetch">
    Depending on `ai.config.ts`, the service queries Pinecone, SuperMemory, or
    both. `redisCache` short-circuits hot lookups and stores serialized chunks
    with TTLs.
  </Step>

  <Step title="Response synthesis">
    Retrieved contexts are injected back into `llmService`. Langfuse tags the
    span with `LANGFUSE_PROMPT_LABEL` so you can replay the exact prompt and
    grounding data when debugging.
  </Step>
</Steps>

## App launch bootstrap

<Steps>
  <Step title="Device handshake">
    `/app/launch` reads `x-device-id`, `x-platform`, and optional user hints,
    then fetches the user/profile record if available.
  </Step>

  <Step title="Context assembly">
    `appController.launch` merges profile data, onboarding state, usage limits,
    social/system URLs, and cached feature flags so the mobile client knows what
    to show.
  </Step>

  <Step title="Response & tracking">
    The launch response is cached briefly in Redis to avoid hammering Mongo, and
    `usageTrackingService` records the bootstrap event for analytics.
  </Step>
</Steps>

## Preprompt + Langfuse sync

<Steps>
  <Step title="Authoring">
    CRUD endpoints under `/api/v1/preprompts/*` write to Mongo with immutable
    versions and optional `public` flags.
  </Step>

  <Step title="Distribution">
    `prePromptService` resolves keys inside the chat orchestrator so each
    conversation can pin a stable system prompt, while
    `src/shared/promptManager` pushes updates to Langfuse.
  </Step>

  <Step title="Webhooks & safety">
    Auth0 Actions call `/api/webhooks/post-*` with `webhookSecretMiddleware` +
    `auth0JwtMiddleware` layered to guard prompt-sync and provisioning flows.
  </Step>
</Steps>

## File attachments & uploads

<Steps>
  <Step title="Upload">
    `/api/v1/files/upload` validates MIME/size, stores the object in Google
    Cloud Storage (when configured), and returns a signed reference ID.
  </Step>

  <Step title="Attachment resolution">
    The chat service calls `resolveAttachmentsForUser` to fetch metadata,
    generate temporary download URLs, and hydrate the message payload before it
    hits the LLM.
  </Step>

  <Step title="Lifecycle management">
    `/api/v1/files/delete` removes objects from GCS and Mongo, while `list/get`
    endpoints allow clients to reuse uploads across conversations.
  </Step>
</Steps>

## Conversation sharing & analytics

<Steps>
  <Step title="Share creation">
    `/api/v1/share/create` stores a snapshot of selected messages plus
    redaction metadata via `ShareRepository`.
  </Step>

  <Step title="Public access">
    `/api/v1/public/share/:slug` validates the signed token from
    `share.config.ts`, hydrates the sanitized transcript, and records view
    analytics.
  </Step>

  <Step title="Revocation & auditing">
    Authenticated routes (`/revoke`, `/analytics`, `/list`) allow users to roll
    keys, see view counts, and clean up stale shares.
  </Step>
</Steps>

## Operational guardrails

* `startupConfig` blocks boot when Mongo or Redis are unhealthy and prints a
  structured readiness report (also surfaced via `/api/v1/health`).
* `usageTrackingService` records every chat/app launch to enforce free-tier
  thresholds—tie into it when adding new consumption surfaces.
* `redisCache` + `redisOps` provide a consistent way to memoize heavy queries,
  issue distributed locks, and expire counters.
* `Langfuse` tracing is mandatory for AI changes; include prompt labels and
  `requestId` so traces connect back to logs.
* `docs/cicdpipeline.mdx` covers the GitHub Actions workflows (`Claim Dev`,
  `Deploy to Dev`, `Release Dev`). Reference it whenever you add migrations or
  new secrets.