qduc/chat repository overview

⁠ChatForge - Modern AI Chat Application

⁠What is ChatForge?

ChatForge is a production-ready AI chat application featuring a Next.js 15 frontend and Node.js backend. It acts as an OpenAI-compatible API proxy with enhanced capabilities including conversation persistence, server-side tool orchestration, and multi-provider support (OpenAI, Anthropic, Gemini).

⁠Key Features

• 🤖 Server-Side Tool Orchestration - Unified tool calling with iterative workflows and intelligent error handling
• 💬 Real-Time Streaming - Server-Sent Events (SSE) with tool execution visibility
• 💾 Conversation Persistence - SQLite-backed storage with automatic retention cleanup
• 🔌 Multi-Provider Support - OpenAI, Anthropic, and Gemini providers
• 🎨 Modern UI - React 19 with markdown rendering and syntax highlighting
• 🔐 Authentication - JWT-based authentication with user management
• 👤 Multi-Tenancy - Per-user provider configuration with isolated conversations
• 🖼️ Vision Support - Image upload with multimodal vision capabilities
• 📎 File Attachments - Text file upload with content extraction
• 🧠 Reasoning Controls - Support for reasoning effort and extended thinking modes
• 💾 Prompt Caching - Automatic cache breakpoints to reduce token costs
• 📓 Journal Tool - Persistent memory for cross-conversation AI context

⁠Quick Start

⁠One-Command Deployment

# Download the compose file
curl -O https://raw.githubusercontent.com/qduc/chat/main/docker-compose.yml

# (Optional) Provide infrastructure secrets
echo "JWT_SECRET=change-me" > .env

# Start the stack
docker compose up -d

Visit http://localhost:3000⁠, register your first user, then open Settings → Providers & Tools to enter your API key.

⁠Using Docker Run

# Create a volume for data persistence
docker volume create chatforge-data

# Run the container
docker run -d \
  --name chatforge \
  -p 3000:3000 \
  -v chatforge-data:/data \
  -e JWT_SECRET=your-secret-here \
  qduc/chatforge:latest

⁠Configuration

⁠Environment Variables

⁠Volumes

• /data - SQLite database and uploaded files (persistent storage required)
• /app/logs - Application logs (optional)

⁠Ports

• 3000 - HTTP server (both API and UI)

⁠Architecture

⁠Single Container Design

The production image uses a multi-stage build that:

1. Builds the Next.js frontend to a static export
2. Compiles backend dependencies with native modules
3. Combines everything into a single runtime container

The Express backend serves:

• /api/* - REST API endpoints
• /* - Static frontend assets

⁠Tech Stack

Frontend:

• Next.js 15.4 + React 19 + TypeScript
• Tailwind CSS 4
• React Markdown with syntax highlighting

Backend:

• Node.js 22 + Express.js 5.1
• SQLite with better-sqlite3
• JWT authentication
• Pino logging

⁠Health Checks

The container includes a built-in health check that monitors the /health endpoint:

# Check container health
docker inspect --format='{{.State.Health.Status}}' chatforge

⁠Data Persistence

Important: Always mount a volume to /data to persist:

• SQLite database (chat.db)
• User-uploaded images and files
• Journal entries

Without a volume, all data will be lost when the container is removed.

⁠Security Considerations

1. JWT Secret: Always set a strong JWT_SECRET in production
2. API Keys: User API keys are stored encrypted in the database
3. User Isolation: All data is scoped to authenticated users
4. Rate Limiting: Built-in rate limiting on API endpoints

⁠Backup and Restore

⁠Backup

# Backup the database
docker cp chatforge:/data/chat.db ./backup-$(date +%Y%m%d).db

⁠Restore

# Stop the container
docker stop chatforge

# Restore the database
docker cp ./backup-20250126.db chatforge:/data/chat.db

# Start the container
docker start chatforge

⁠Updating

# Pull the latest image
docker pull qduc/chatforge:latest

# Stop and remove the old container
docker stop chatforge && docker rm chatforge

# Start a new container with the same configuration
docker run -d \
  --name chatforge \
  -p 3000:3000 \
  -v chatforge-data:/data \
  -e JWT_SECRET=your-secret-here \
  qduc/chatforge:latest

⁠Supported Platforms

• linux/amd64
• linux/arm64

⁠Documentation

• GitHub Repository: github.com/qduc/chat⁠
• Installation Guide: docs/INSTALLATION.md⁠
• API Documentation: docs/backend_api_spec.md⁠
• Architecture: docs/ARCHITECTURE.md⁠

⁠Support

• Issues: GitHub Issues⁠
• Discussions: GitHub Discussions⁠

⁠License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

Note: This is a self-hosted application. You need to provide your own API keys for OpenAI, Anthropic, or Gemini through the Settings interface after deployment.