Skip to main content
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).

​
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

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