AIChatRoom/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

AI Chat Room (AI聊天室) is a multi-agent collaborative discussion platform. Users configure AI providers, create agents with different roles, and let them discuss in chat rooms to reach consensus.

Stack: FastAPI (Python 3.11+) backend + React 18 (TypeScript) frontend + MongoDB database. Real-time communication via WebSockets.

Development Commands

Docker (Recommended)

# Start all services
docker-compose up -d

# Rebuild after changes
docker-compose up -d --build

# View logs
docker-compose logs -f backend
docker-compose logs -f frontend

Backend (Local)

cd backend
python -m venv venv
venv\Scripts\activate  # Windows: activate, Linux/Mac: source venv/bin/activate
pip install -r requirements.txt
python main.py

Backend runs on http://localhost:8000 - API docs at http://localhost:8000/docs

Frontend (Local)

cd frontend
npm install
npm run dev       # Development server (Vite)
npm run build     # Production build (tsc && vite build)

Frontend runs on http://localhost:3000

Architecture

Backend Structure

• adapters/ - AI provider integrations using Adapter pattern
  • base_adapter.py - Abstract base class with ChatMessage, AdapterResponse, BaseAdapter
  • Each adapter implements chat(), chat_stream(), test_connection()
  • Supported: OpenRouter, Zhipu (智谱), MiniMax, Kimi, DeepSeek, Gemini, Ollama, LLM Studio
• models/ - Beanie ODM documents for MongoDB
• services/ - Business logic layer
  • discussion_engine.py - Core multi-agent discussion orchestration
  • consensus_manager.py - Moderator agent evaluates if consensus reached
  • message_router.py - WebSocket message routing
• routers/ - FastAPI route handlers (providers, agents, chatrooms, discussions)
• utils/ - encryption.py (API keys), proxy_handler.py, rate_limiter.py

Frontend Structure

• src/stores/ - Zustand state management
• src/services/ - API client and WebSocket client
• src/pages/ - Dashboard, ProviderConfig, AgentManagement, ChatRoom, DiscussionHistory
• src/components/ - Reusable UI components using Ant Design

Key Data Flow

1. User creates agents (role + system prompt) and assigns AI providers
2. Chat room created with selected agents + optional moderator
3. Discussion started: discussion_engine.py orchestrates turn-based agent interactions
4. Each round: agents receive context and decide whether to speak (role relevance)
5. Moderator agent periodically checks for consensus via consensus_manager.py
6. WebSocket streams messages in real-time to frontend

Adding New AI Providers

1. Create new adapter in backend/adapters/ inheriting from BaseAdapter
2. Implement async methods: chat(), chat_stream(), test_connection()
3. Register in backend/adapters/__init__.py

Configuration

Environment variables in .env:

• MONGODB_URL - MongoDB connection string
• MONGODB_DB - Database name (default: ai_chatroom)
• SECRET_KEY - JWT signing key
• ENCRYPTION_KEY - 32-byte key for API key encryption
• DEFAULT_HTTP_PROXY / DEFAULT_HTTPS_PROXY - Proxy for overseas APIs

Backend config in backend/config.py - Pydantic Settings with defaults.

Important Notes

• All async/await - Python async functions throughout backend
• API keys encrypted at rest using cryptography Fernet
• WebSocket heartbeat every 30s (WS_HEARTBEAT_INTERVAL)
• CORS origins configured in settings for local development
• MongoDB indexes created automatically by Beanie on startup
• Chinese language UI (README and comments in Chinese)