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

# Service catalog

> What lives under src/services and how each module interacts with shared plumbing.

<Note>
  Think of this as the “who owns what” reference. Every entry links back to the
  folders you touch during feature work so new contributors can orient quickly.
</Note>

## Request-facing services

<AccordionGroup>
  <Accordion title="Auth (`src/services/auth`)">
    * Routes: `/api/v1/auth/*` for OTP, passwordless login, refresh, Google token
      exchange, and sign-out. Webhook handlers under
      `/api/v1/auth/webhooks/*` receive Auth0 Actions (post-registration/login).
    * Controllers wire `auth0JwtMiddleware`, `webhookSecretMiddleware`, and the
      Mongo `userRepository` so JWT subjects are mirrored in our database.
    * Services handle OTP generation/verification, device binding, session
      revocation, and Auth0 Management API calls when credentials are present.
    * Docs to cross-reference: `/docs/api-reference/auth*` plus
      `WEB_GOOGLE_AUTH_GUIDE.md` and `MOBILE_GOOGLE_AUTH_GUIDE.md`.
  </Accordion>

  <Accordion title="AI chat (`src/services/ai`)">
    * Routes: `/api/v1/ai/chat` (sync + streaming), `/api/v1/ai/health`.
    * `ChatOrchestrationService` coordinates conversation creation,
      `MessageRepository`, `MemoryService` (SuperMemory + Mongo), the `llmService`
      abstraction around OpenAI/Anthropic, `usageTrackingService`, and
      `prePromptService`.
    * File attachments flow through `file-attachment.helper.ts`, which resolves
      inline uploads or stored files before they hit the LLM.
    * Every completion is traced via Langfuse (`instrumentation.ts`) and respects
      per-user quotas.
  </Accordion>

  <Accordion title="RAG (`src/services/rag`)">
    * Routes: `/api/v1/rag/*` for retrieval-augmented answers and tooling around
      Pinecone / SuperMemory indices.
    * Uses `ai.config.ts` to decide which vector store/provider to fan out to and
      shares the Redis cache helpers for dedup + hydration.
    * RAG responses are logged with the same `X-Request-ID` plus Langfuse spans so
      you can replay failing traces.
  </Accordion>

  <Accordion title="Context Manager (`src/services/contextManager`)">
    * Owns onboarding context, user memory slots, and syncs with SuperMemory.
    * Routes: `/api/v1/context/*` for CRUD on profile facets, document
      attachments, and preference toggles.
    * Services like `MemoryService`, `ContextService`, and `ProfileSyncService`
      reuse the shared repositories and Redis caching to hydrate chat sessions.
  </Accordion>

  <Accordion title="Conversations (`src/services/conversations`)">
    * Routes under `/api/v1/user/conversations*` give clients list/search/detail,
      archive/restore/delete, and message pagination.
    * Controllers use `ConversationRepository` + `MessageRepository` directly,
      reusing the same schema as the chat orchestrator so histories stay in sync.
    * All endpoints require `auth0JwtMiddleware` and return the shared
      `successResponse` envelope.
  </Accordion>

  <Accordion title="Chat Share (`src/services/chatShare`)">
    * Routes: `/api/v1/share/*` (authenticated) and `/api/v1/public/share/*`
      (tokenized public viewers).
    * `ShareService` composes signed URLs with `share.config.ts`, enforces TTLs,
      and stores view analytics alongside the share document.
    * Public routes still go through `promptWebhookRoutes` to ensure shared
      prompts stay current.
  </Accordion>

  <Accordion title="File uploads (`src/services/fileUpload`)">
    * Routes: `/api/v1/files/upload|get|list|delete`.
    * `gcs-storage.service.ts` orchestrates Google Cloud Storage buckets when
      `GCS_PROJECT_ID`/`GCS_BUCKET_NAME` are set; otherwise the service gracefully
      degrades and blocks uploads.
    * Files can be attached to chats (see `ai/utils/file-attachment.helper.ts`)
      and are automatically scanned for metadata before being persisted.
  </Accordion>

  <Accordion title="Profile (`src/services/profile`)">
    * Routes: `/api/v1/profile/*` for retrieving/updating user-level metadata
      (names, communication preferences, linked brokerage accounts, etc.).
    * Heavily reuses `userRepository` and `profile.service.ts` to ensure updates
      stay consistent with the Auth0-backed identity model.
  </Accordion>

  <Accordion title="App bootstrap (`src/services/app`)">
    * Routes: `/app/launch` and `/app/health`, consumed by the mobile clients
      before hitting the authenticated APIs.
    * `appController.launch` stitches together device headers, user/profile data,
      feature flags, social links, and free-tier thresholds so the app can decide
      whether onboarding is required.
    * This path touches MongoDB, Redis, and the `usageTrackingService`, so keep
      those services healthy before debugging app issues.
  </Accordion>

  <Accordion title="Preprompts (`src/services/preprompts`)">
    * Routes: `/api/v1/preprompts/*` for CRUD + public listings.
    * Drives both chat orchestration (via `prePromptService`) and the Langfuse
      prompt manager. Every preprompt is versioned and can be exposed publicly
      for marketing/SEO use cases.
  </Accordion>
</AccordionGroup>

## Supporting packages

* **`src/services/database`** – typed repositories and interfaces for users,
  conversations, messages, shares, files, etc. Repositories own index creation
  and run during `startupConfig.initialize()` so Mongo stays optimized.
* **`src/shared/promptManager`** – webhook receivers and sync scripts that keep
  Langfuse prompt definitions aligned with the preprompt store.
* **`src/services/brokers`** – integrations with Groww and Zerodha for account
  linking plus trade history ingest.
* **`src/services/ingestor`** – connectors that pull statements/SMS into the
  context store for downstream analysis.
* **`src/services/insights`** – higher-level analytics and notification logic
  built on top of context, conversations, and RAG results.
* **`src/shared/services`** – cross-cutting helpers such as
  `usage-tracking.service.ts`, rate-limit utilities, and AI tracing.
* **`infra/terraform` + `infra/k8s`** – infrastructure-as-code for Cloud Run,
  VPC, secret management, and (optional) Kubernetes deployments.

## How to add a new surface

1. Scaffold `src/services/<name>/{controllers,routes,services,types}` following
   the existing verticals.
2. Register the router in `server.ts` under a clear prefix
   (`/api/v1/<name>` or `/app/<name>`).
3. Leverage repositories in `src/services/database` instead of re-querying
   MongoDB directly.
4. Update `/docs/api-reference` **and** the relevant `/docs/codebase/*` page so
   the Mintlify sidebar stays trustworthy (Mintlify recommends keeping guides
   concise and task-focused, see their [style guide](https://www.mintlify.com/docs/guides/style-and-tone?utm_source=openai)).