Architecture

How ChatJS is structured and how data flows through the system

System Overview

The application uses:

• Next.js App Router for the frontend and API routes
• PostgreSQL (via Drizzle ORM) for persistent data (users, chats, messages, documents)
• Redis for ephemeral data (resumable streams, caching). See Resumable Streams
• AI SDK to connect to multiple AI providers through a gateway abstraction
• useThread to manage the selected conversation path, message tree, and independent response runs. See useThread
• Files SDK through a configured file storage provider for attachments and generated media
• tRPC for end-to-end type-safe API routes between client and server
• Langfuse (optional) for LLM observability, tracing, and analytics

Chat Message Flow

When a user sends a message:

ChatJS stores messages with normalized parts (text, tool calls, files, reasoning) so you can query and stream updates efficiently. Each active assistant response has its own run. When you navigate to another branch, that response keeps streaming.

If resumable streams are enabled, response chunks are published to Redis so clients can reconnect mid-generation without losing progress.

Configuration

All settings flow from a single source:

1. chat.config.ts - Your configuration
2. lib/config/ - Parse and apply defaults
3. lib/env.ts - Validate environment variables
4. Runtime - Features enabled/disabled

This ensures type-safe configuration and build-time validation of environment variables. See Configuration for the full reference.