Public

Assistant Chat | blade47/comp Wiki | doc0

Assistant Chat

Last updated Oct 6, 2026

Relevant source files

The following files were used as context for generating this wiki page:

The Assistant Chat module provides an API for managing ephemeral chat history for an AI assistant. It allows users to retrieve, save, and clear their conversation history, scoped to their user ID and organization ID. The history is stored in a Redis-compatible key-value store with a default time-to-live (TTL) of 7 days, designed for session context rather than long-term archiving.

This module integrates with the application's authentication system to ensure that chat history operations are user-scoped and secure. It leverages a flexible Redis client that can connect to an Upstash Redis instance or fall back to an in-memory store for development or testing environments.

Architecture Overview

The Assistant Chat feature is implemented as a NestJS module, encapsulating its components: a controller for handling API requests, a service for business logic and data manipulation, and DTOs for data validation and transfer. It relies on a Redis client for persistence and integrates with the application's authentication module.

Ephemeral Session Context

The chat history is designed to be ephemeral, with a default Time-To-Live (TTL) of 7 days. This means chat sessions are not intended for long-term storage or searchable archives but rather for maintaining context within recent interactions. The TTL can be configured via the ASSISTANT_CHAT_TTL_SECONDS environment variable.

Sources: apps/api/src/assistant-chat/assistant-chat.module.ts, apps/api/src/assistant-chat/assistant-chat.controller.ts, apps/api/src/assistant-chat/assistant-chat.service.ts

API Endpoints

The AssistantChatController exposes a set of RESTful endpoints for managing assistant chat history. All endpoints are protected by the HybridAuthGuard and require user-scoped authentication. API key authentication is explicitly disallowed for chat history operations.

Base Path

/v1/assistant-chat Sources: apps/api/src/assistant-chat/assistant-chat.controller.ts

Endpoints

Method	Path	Description	Request Body	Response Body
`GET`	`/history`	Retrieves the current user-scoped assistant chat history.	N/A	`{ messages: AssistantChatMessage[] }`
`PUT`	`/history`	Replaces the current user-scoped assistant chat history with new messages.

Authentication and Authorization

All endpoints are secured using HybridAuthGuard. The AuthContext decorator is used to extract user and organization information from the authenticated request. A BadRequestException is thrown if the organizationId or userId is missing, or if the request is authenticated via an API key instead of a user JWT.

User-Scoped Access Only

Assistant chat history operations are strictly limited to user-authenticated requests (Bearer JWT). Requests authenticated with an API key will be rejected with a BadRequestException. This ensures that chat history is always tied to a specific user and organization.

Sources: apps/api/src/assistant-chat/assistant-chat.controller.ts

Data Models

The core data structure for assistant chat is AssistantChatMessage, which represents a single message in the conversation.

AssistantChatMessage

This type defines the structure of a single message, including its ID, role (user or assistant), text content, and creation timestamp.

Field	Type	Description	Example
`id`	`string`	Unique identifier for the message.	`msg_abc123`
`role`	`'user' \| 'assistant'`	The sender of the message.	`user`
`text`

Data Transfer Objects (DTOs)

The assistant-chat.dto.ts file defines DTOs used for API request bodies and Swagger documentation.

Sources: apps/api/src/assistant-chat/assistant-chat.dto.ts

Service Logic

The AssistantChatService handles the core business logic for chat history management, including interaction with the Redis client and data validation.

Key Generation

A unique key is generated for each user's chat history in Redis, combining the organization ID and user ID. This ensures data isolation between different users and organizations.

const getAssistantChatKey = ({
  organizationId,
  userId,
}: GetAssistantChatKeyParams): string => {
  return `assistant-chat:v1:${organizationId}:${userId}`;
};

Sources: apps/api/src/assistant-chat/assistant-chat.service.ts

History Operations

getHistory(params): Retrieves the chat history for a given user and organization. It fetches raw data from Redis and then uses a Zod schema (StoredMessagesSchema) for safe parsing and validation. If parsing fails, an empty array is returned.
saveHistory(params, messages): Stores the provided chat messages for a user and organization. It first validates the incoming messages against StoredMessagesSchema to maintain data integrity in the cache. The data is stored with a configurable TTL.
clearHistory(params): Deletes the chat history associated with a user and organization from Redis. Sources: apps/api/src/assistant-chat/assistant-chat.service.ts

Data Validation

The AssistantChatService uses Zod schemas to ensure the integrity and shape of the stored chat messages.

StoredMessageSchema: Validates individual chat messages.
StoredMessagesSchema: Validates an array of StoredMessageSchema objects. Sources: apps/api/src/assistant-chat/assistant-chat.service.ts

Redis Client

The upstash-redis.client.ts file provides an abstraction over Redis interactions. It dynamically chooses between an actual Upstash Redis client and an in-memory implementation based on environment variables.

Sources: apps/api/src/assistant-chat/upstash-redis.client.ts

`assistantChatRedisClient`

This client object provides get, set, and del methods, abstracting the underlying storage mechanism. It's used by the AssistantChatService to interact with the chat history store.

Was this page helpful?

Auth Security

Evidence Forms

SaveAssistantChatHistoryDto