# 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)
```bash
# 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)
```bash
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)
```bash
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/](backend/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/](backend/models/)** - Beanie ODM documents for MongoDB
- **[services/](backend/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/](backend/routers/)** - FastAPI route handlers (providers, agents, chatrooms, discussions)
- **[utils/](backend/utils/)** - encryption.py (API keys), proxy_handler.py, rate_limiter.py

### Frontend Structure
- **[src/stores/](frontend/src/stores/)** - Zustand state management
- **[src/services/](frontend/src/services/)** - API client and WebSocket client
- **[src/pages/](frontend/src/pages/)** - Dashboard, ProviderConfig, AgentManagement, ChatRoom, DiscussionHistory
- **[src/components/](frontend/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](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)