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

Messages are stored with normalized parts (text, tool calls, files, reasoning) allowing efficient querying and streaming updates.

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.