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

​
Request-facing services

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

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