A full-featured Next.js 16 AI chat application featuring branching message trees, real-time streaming responses, multi-format artifact rendering (Markdown, HTML, XLSX, Mermaid diagrams), file handling, and integrated Model Context Protocol (MCP) servers. Built with TypeScript, PostgreSQL, Better Auth, and the Vercel AI SDK—deploy with confidence.
- Branching conversations — Edit any message to create sibling branches non-destructively; navigate trees intuitively
- Real-time streaming — Responses stream with support for reasoning tokens and tool calls
- Message trees — Explore alternative conversation paths via interactive branch controls
- Multi-method login — Email/password, GitHub/Discord OAuth, WebAuthn passkeys
- Multi-factor authentication — TOTP (time-based one-time password) and backup codes
- Session tracking — Device fingerprinting and secure session revocation
- Attachment handling — Upload images, PDFs, text, and Excel spreadsheets directly in messages
- S3/MinIO storage — Secure cloud storage with presigned URLs for access control
- File bridges — MCP-powered file operations including Excel staging and auto-re-upload
- Streaming via OpenRouter — Access multiple LLMs (GPT-4, Claude, Mistral, etc.)
- Reasoning tokens — Support for extended thinking models with collapsible output
- Tool-call integration — Automatic tool invocation and result handling
- Artifacts & canvas — Multi-view rendering (Markdown, HTML, XLSX, Mermaid) with persistent edits and export
- Stdio and HTTP transports — Configure local executables or remote HTTP servers
- Per-message tool selection — Choose which tools to expose for each AI request
- Custom tool integration — Add application-specific capabilities (e.g., Excel via MCP)
- Projects — Group related chats and share custom system prompts
- Assistants — Define AI personas with custom prompts and avatars; reuse across chats
- Knowledge bases — Organise reference material (UI-only, ready for RAG integration)
- Account settings — Profile updates, password changes, and security configuration
- Slash-commands — Reusable prompt shortcuts (e.g.,
/summarise) prepended before sending - Email configuration — Transactional emails via Postmark for auth and notifications
- PostgreSQL 17 — Relational schema with Drizzle ORM type safety
- Message persistence — Full conversation history with tree-based branching
- Optimistic updates — Client-side Zustand store synced reliably to the database
- KaTeX rendering — Mathematical notation with full LaTeX support
- Markdown processing — Rich text with code highlighting and syntax support
- Responsive design — Mobile-first UI with Tailwind CSS and shadcn/ui components
- Next.js — React framework with App Router and Server Components
- React — Component-based UI library
- TypeScript — Type-safe JavaScript
- Tailwind CSS — Utility-first CSS framework
- Shadcn UI — Composable React component library
- Radix UI / Base UI — Accessible, unstyled component primitives
- Sonner — Toast notifications
- Zustand — Lightweight client-side state store
- React Markdown — Markdown to React components
- Mermaid — Diagram and flowchart rendering
- KaTeX — Mathematical typesetting
- unpdf — PDF text extraction
- BlockNote — Rich text editor
- Better Auth — Email/password, OAuth, passkeys, and TOTP support
- Postmark — Transactional email service
- MinIO (AWS SDK v3) — S3-compatible object storage
- PostgreSQL — Relational database
- Drizzle ORM — Type-safe SQL query builder and migrations
- Vercel AI SDK — Streaming responses and tool integration
- OpenRouter API — Multi-model LLM provider
- @ai-sdk/mcp — Model Context Protocol integration
- @modelcontextprotocol/sdk — Official MCP TypeScript SDK
- Node.js: 22.x or higher
- npm: 9.x or higher (bundled with Node.js)
- PostgreSQL 17.0 — Primary data store for users, chats, messages, and application state
- S3/MinIO — S3-compatible object storage for file uploads and attachments (or AWS S3 in production)
- OpenRouter API — LLM provider for AI conversation capabilities (account required; free tier available)
- Postmark — Transactional email service for authentication and notifications (account required)
- Python, Java, Kotlin, Go, Rust, C++ (Optional) — Required for running MCP servers locally but different languages.
Docker/Podman can be used to run PostgreSQL and MinIO locally without cloud dependencies.
Follow these steps to set up and run the AI Client locally.
Clone the repository to your local machine:
git clone https://github.com/mbeps/ai-client.git
cd ai-clientInstall all required Node.js dependencies:
npm installFor local development, create .env.local in the project root:
cp .env.example .env.localThe docker-compose.yml file reads from .env to configure PostgreSQL and MinIO. Key variables:
DB_HOST,DB_PORT,DB_USER,DB_PASSWORD,DB_NAME— PostgreSQL configurationS3_ACCESS_KEY,S3_SECRET_KEY— MinIO root credentials
These are referenced in docker-compose.yml and should be defined in .env (defaults are provided).
# PostgreSQL (docker-compose)
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=password
DB_NAME=better_auth_tutorial
# MinIO (docker-compose)
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin# Database (Next.js application)
DATABASE_URL=postgresql://postgres:password@localhost:5432/better_auth_tutorial
# Authentication
BETTER_AUTH_SECRET=your-secure-random-string-here
BETTER_AUTH_URL=http://localhost:3000
# AI & Language Models
OPENROUTER_API_KEY=sk-or-...
# Storage (MinIO/S3)
S3_ENDPOINT=http://localhost:9000
S3_REGION=us-east-1
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET=ai-client-uploads
# Email Service
POSTMARK_SERVER_TOKEN=your-postmark-token-here
POSTMARK_FROM_EMAIL=noreply@yourdomain.com
# OAuth (optional)
CLIENT_ID_GITHUB=your-github-oauth-client-id
CLIENT_SECRET_GITHUB=your-github-oauth-secret
CLIENT_ID_DISCORD=your-discord-oauth-client-id
CLIENT_SECRET_DISCORD=your-discord-oauth-secretCore Application
DATABASE_URL(required) — PostgreSQL connection string- Format:
postgresql://user:password@host:port/database - Ensure it matches your
.envvariables for the container
- Format:
BETTER_AUTH_SECRET(required) — Authentication secret key- Generate:
openssl rand -base64 32 - Keep secure; never commit to version control
- Generate:
BETTER_AUTH_URL(required) — Auth callback URL (http://localhost:3000for dev)
AI & Language Models
OPENROUTER_API_KEY(required) — API key from https://openrouter.ai- Free account allows testing; paid usage scales with LLM calls
Storage
S3_ENDPOINT— MinIO/S3 endpoint URL (default:http://localhost:9000)S3_REGION— AWS region or MinIO region (default:us-east-1)S3_ACCESS_KEY— MinIO root user (default:minioadmin)S3_SECRET_KEY— MinIO root password (default:minioadmin)S3_BUCKET— Bucket name for uploads (default:ai-client-uploads)
Email Service
POSTMARK_SERVER_TOKEN(required) — API token from https://postmark.comPOSTMARK_FROM_EMAIL(required) — Verified sender email address
OAuth (Optional)
CLIENT_ID_GITHUB/CLIENT_SECRET_GITHUB— GitHub OAuth credentialsCLIENT_ID_DISCORD/CLIENT_SECRET_DISCORD— Discord OAuth credentials
These instructions are needed if you wish to run PostgreSQL and MinIO locally using Docker (or Podman). You can also connect to external services (e.g., managed PostgreSQL, AWS S3) by configuring the appropriate environment variables.
Start PostgreSQL and MinIO using Docker (or Podman):
docker-compose up -dVerify both services are running:
docker psYou should see postgres and minio containers. MinIO console is available at http://localhost:9001.
Run database migrations:
npm run db:migrateStart the development server:
npm run devThe application will be available at http://localhost:3000.
Alternatively, you can build and run the application:
npm run build
npm startThe application is built on a modern, type-safe architecture centred on reliable real-time communication. The frontend (Next.js + React) uses a Zustand store for optimistic client-side state management; all mutations trigger Server Actions that persist to PostgreSQL via Drizzle ORM. This pattern delivers instant UI feedback while guaranteeing consistency. The API layer integrates the Vercel AI SDK for streaming responses from OpenRouter, handling tool calls transparently and re-injecting artifact edits into the AI context as tool-result history—ensuring the assistant always understands what users have modified.
Conversations are structured as message trees: each message has an optional parent_id, enabling non-destructive branching when users edit. The currentLeafId on the chat tracks the active path, allowing exploration of alternative conversation threads. Artifacts (rendered outputs like Markdown, HTML, Excel, and Mermaid diagrams) are managed via an internal manage_artifact tool that the AI invokes automatically; user edits re-validate paths and update metadata in the database, then get re-injected so the AI sees the modified state. File attachments are stored in MinIO/S3 with presigned URLs, preserving access control and privacy. Authentication leverages Better Auth for multi-method login (email/password, OAuth, WebAuthn, TOTP), with session fingerprinting for security.
MCP Server integration allows custom tools to be registered—either as local stdio executables or remote HTTP endpoints. When users send a message, they select which tools to expose; the SDK discovers capabilities, the AI calls them as needed, and results flow back into the conversation. Projects and Assistants provide reusable context: projects group chats and apply shared system prompts, whilst assistants define personas that persist across multiple chats. This layered design—from the database up through optimistic updates to real-time streaming—creates a responsive, scalable foundation suitable for both individual use and collaborative workflows.
- Next.js — React meta-framework with App Router, Server Components, and Server Actions
- React — Component-based UI library for building interactive interfaces
- TypeScript — Typed superset of JavaScript with compile-time safety
- Better Auth — Multi-method authentication (email/password, OAuth, passkeys, TOTP 2FA)
- Radix UI — Unstyled, accessible component primitives for custom design systems
- PostgreSQL — Relational database for persistent storage
- Drizzle ORM — Type-safe SQL query builder with migrations and introspection
- Vercel AI SDK — Streaming responses, tool integration, and language model abstraction
- OpenRouter API — Multi-model LLM provider with unified API
- Model Context Protocol — Protocol for AI tool and server integration
- Shadcn UI — Copy-paste React component library built on Radix UI
- Tailwind CSS — Utility-first CSS framework for rapid styling
- Sonner — Toast notification component library
- React Hook Form — Performant form handling with minimal re-renders
- Zod — TypeScript-first schema validation for runtime safety
- Zustand — Lightweight, flexible state management without boilerplate
- React Markdown — Parse and render Markdown to React components
- Mermaid — Diagram rendering for flowcharts, sequence diagrams, and more
- KaTeX — Mathematical typesetting and LaTeX notation rendering
- unpdf — PDF text extraction and processing
- MinIO — S3-compatible object storage for file uploads and assets
- AWS SDK v3 — AWS service client for S3/MinIO
- xlsx — Excel file parsing, generation, and manipulation
- UUID — Standard UUID generation for unique identifiers
- Date-fns — Date manipulation, formatting, and parsing utilities
- cmdk — Fast command/search interface component
- Resizable Panels — Draggable, resizable layout panels
- Vaul — Mobile drawer/sheet component
- BlockNote — Rich text editor for document editing
- Postmark — Transactional email service for reliable delivery
- Node PostgreSQL — Node.js PostgreSQL client library
- Turbopack — Next-generation bundler integrated with Next.js
- ESLint — JavaScript linter for code quality and consistency
MIT