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

# Codebase architecture

> How the Bun + Hono backend is wired together and where to look first.

<Note>
  Start here if you need a mental model of the backend. The goal is to keep the
  structure skimmable and mirror the style/tone guidance from the Mintlify docs
  (short sections, active voice, plentiful links).
</Note>

## Runtime stack

* **Runtime** – Bun + TypeScript with Hono as the HTTP framework (`server.ts`).
* **Persistence** – MongoDB (primary source of truth) plus Redis/Upstash for
  caching and rate limiting (`src/shared/config/mongodb.config.ts`,
  `src/shared/config/redis.config.ts`).
* **AI + Retrieval** – OpenAI/Anthropic via `@ai-sdk/*`, Pinecone +
  SuperMemory-backed memories, Google Cloud Storage for binary artifacts.
* **Identity** – Auth0 JWTs enforced by the shared middleware
  (`src/shared/middlewares/auth0-jwt.middleware.ts`), optional webhook secrets
  for Auth0 Actions.
* **Observability** – `instrumentation.ts` boots OpenTelemetry with the
  Langfuse span processor before the server mounts. Every request receives an
  `X-Request-ID` and structured logs flow through `src/shared/utils/logger.ts`.

## Entry point & middleware pipeline

1. `server.ts` imports `./instrumentation` *first* to enable tracing, creates a
   `Hono` app, attaches logging + CORS, and stamps each request with a UUID that
   is read back via `BaseController.getRequestId`.
2. `startupConfig.initialize()` validates the Zod-based env schema, connects to
   MongoDB/Redis, optionally wires Google Cloud Storage, and logs per-service
   health before serving traffic.
3. Routes are mounted by vertical (`/api/v1/auth`, `/api/v1/ai`, `/app/*`, etc.)
   and reuse shared helpers (`successResponse`, `errorResponse`,
   `errorHandlerMiddleware`).
4. Webhooks under `/api/webhooks/*` apply `webhookSecretMiddleware` *before*
   hitting Auth0 JWT verification so third parties must present the shared
   secret.

## Directory map

| Path                       | What lives there                                                                                                                                                                                             |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `server.ts`                | Hono app composition, request ID middleware, route registration, graceful shutdown                                                                                                                           |
| `instrumentation.ts`       | OpenTelemetry + Langfuse initialization and shutdown hooks                                                                                                                                                   |
| `src/services/*`           | Verticalized HTTP services (Auth, AI, RAG, Context Manager, Conversations, Chat Share, File Upload, Profile, App bootstrap, Preprompts, etc.) each with `controllers/`, `routes/`, `services/`, and `types/` |
| `src/services/database`    | All MongoDB repositories, interfaces, and shared query helpers (conversation/message/share/user stores)                                                                                                      |
| `src/shared/config`        | Centralized env schema, startup orchestration, Auth0, AI, Redis, SuperMemory, Langfuse, and share-link configuration                                                                                         |
| `src/shared/middlewares`   | Cross-cutting middleware (Auth0 JWT, webhook secret validation, CORS, rate limiting, error handling)                                                                                                         |
| `src/shared/utils`         | Logger, base controller/service classes, response helpers, error types, title generators, etc.                                                                                                               |
| `src/shared/promptManager` | Prompt registry + webhook routes for syncing Langfuse prompts                                                                                                                                                |
| `infra/`                   | Kubernetes manifests and Terraform modules for GCP/Cloud Run deployments                                                                                                                                     |
| `docs/`                    | The Mintlify site (including this page) that documents the platform                                                                                                                                          |

## Shared modules worth knowing

* **Config + startup** – `startup.config.ts` is the gatekeeper. It validates env
  vars, spins up MongoDB/Redis, checks optional providers (Auth0 management API,
  Langfuse, SuperMemory, Share service), and exits early if critical systems are
  missing. Repositories register their Mongo indexes from here.
* **Middlewares** – `auth0JwtMiddleware` fetches JWKS keys lazily, looks up or
  auto-creates the Mongo user, and injects `userId`, roles, and permissions into
  every request context. `webhookSecretMiddleware` guards Auth0 Actions and other
  inbound hooks before JWT validation.
* **Caching + rate limiting** – `redis-cache.service.ts` wraps ioredis for
  distributed caches with TTLs and pattern invalidation, while `redisOps` gives
  low-level helpers for atomic counters and expiry. The `getEnv()` schema
  supports both self-hosted Redis and Upstash via REST credentials.
* **Prompt + memory orchestration** – `src/shared/promptManager` keeps Langfuse
  prompts synchronized, and `MemoryService` manages SuperMemory plus Mongo-based
  long-term storage for conversations.
* **Usage tracking & quotas** – `usageTrackingService` logs each message to
  support free-tier enforcement and emit telemetry.

## External surfaces & infrastructure

* **Auth0** – Used for JWT verification, webhooks (post-login/registration), and
  optional management API calls. Keys and audience are declared in
  `auth.config.ts`.
* **Google Cloud** – Cloud Run hosts the Bun server; Google Cloud Storage handles
  binary uploads via the file upload service, and Cloud Build + GitHub Actions
  drives deployments (see `/docs/cicdpipeline.mdx`).
* **Pinecone & SuperMemory** – RAG indices and personalized memory live outside
  MongoDB. The AI config (`ai.config.ts`) controls whether retrieval and memory
  augmentation are active per environment.
* **Langfuse** – All AI requests emit spans (see `instrumentation.ts`). Prompt
  labels (`LANGFUSE_PROMPT_LABEL`) tie traces back to specific orchestrations.

## How to extend safely

1. **Follow the workspace layout** – new verticals belong under
   `src/services/<domain>` with `controllers`, `routes`, `services`, and
   `types/interfaces`.
2. **Register routes centrally** – mount your `Hono` router in `server.ts` to
   ensure request logging, auth, and error handling stay consistent.
3. **Document alongside code** – pair any non-trivial change with an update to
   either `/docs/codebase/*` or the relevant API reference page so other
   developers can find the contract quickly.
4. **Lean on shared helpers** – reuse `BaseController`, `successResponse`,
   `auth0JwtMiddleware`, `redisCache`, and the repository layer instead of
   re-implementing plumbing.

## Conversation metadata & tracking

Conversations now capture rich metadata to support analytics and improved UX:

* **`preprompt_key`** – Stores which pre-prompt (if any) was used when creating
  the conversation. This enables tracking pre-prompt popularity and user
  engagement patterns. Automatically set when a user selects a pre-prompt before
  starting a chat.
* **`input_type`** – Tracks how the conversation was initiated: `'text'` for
  plain messages, `'file'` for file uploads, or `'voice'` for voice input.
  Automatically determined by the chat orchestration service based on the
  presence of attachments.
* **`type`** – Differentiates `'chat'` (main chat) from `'second_opinion'`
  (structured financial advice) conversations.

These fields are populated at conversation creation time
(`ConversationRepository.create`) and are included in all conversation list and
detail responses. The metadata supports:

* **Analytics queries** – Track which pre-prompts drive engagement, measure
  file-upload vs text-only conversations, and segment users by interaction
  patterns.
* **UI enhancements** – Display appropriate icons (file/voice badges), show
  pre-prompt tags in conversation lists, and filter/group conversations by type.
* **Future personalization** – Use historical input preferences to suggest
  optimal interaction modes or popular pre-prompts.

See `CONVERSATION_METADATA_IMPLEMENTATION.md` in the project root for complete
implementation details, database schema changes, and usage examples.