Skip to main content
These walkthroughs map directly to the production code so you can jump from “what happens?” to “where is it implemented?” without chasing Slack threads.

​
Authenticated API call

1

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

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

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.

​
Chat orchestration & memory

1

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

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

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.

​
Retrieval-augmented answers

1

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

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

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.

​
App launch bootstrap

1

Device handshake

/app/launch reads x-device-id, x-platform, and optional user hints, then fetches the user/profile record if available.
2

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

Response & tracking

The launch response is cached briefly in Redis to avoid hammering Mongo, and usageTrackingService records the bootstrap event for analytics.

​
Preprompt + Langfuse sync

1

Authoring

CRUD endpoints under /api/v1/preprompts/* write to Mongo with immutable versions and optional public flags.
2

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

Webhooks & safety

Auth0 Actions call /api/webhooks/post-* with webhookSecretMiddleware + auth0JwtMiddleware layered to guard prompt-sync and provisioning flows.

​
File attachments & uploads

1

Upload

/api/v1/files/upload validates MIME/size, stores the object in Google Cloud Storage (when configured), and returns a signed reference ID.
2

Attachment resolution

The chat service calls resolveAttachmentsForUser to fetch metadata, generate temporary download URLs, and hydrate the message payload before it hits the LLM.
3

Lifecycle management

/api/v1/files/delete removes objects from GCS and Mongo, while list/get endpoints allow clients to reuse uploads across conversations.

​
Conversation sharing & analytics

1

Share creation

/api/v1/share/create stores a snapshot of selected messages plus redaction metadata via ShareRepository.
2

Public access

/api/v1/public/share/:slug validates the signed token from share.config.ts, hydrates the sanitized transcript, and records view analytics.
3

Revocation & auditing

Authenticated routes (/revoke, /analytics, /list) allow users to roll keys, see view counts, and clean up stale shares.

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