# CLAUDE.md

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

## Project Overview

MoAI (Master of AIs) is a multi-AI collaborative brainstorming platform. Multiple AI models (Claude, GPT, Gemini) discuss topics together in structured rounds, working toward consensus. Phase 1 is a Telegram bot; Phase 2 adds a web UI.

## Build & Development Commands

```bash
# Install dependencies (use uv or pip)
uv sync                          # or: pip install -e ".[dev]"

# Run the bot
python -m moai.bot.main

# Run tests
pytest                           # all tests
pytest tests/test_models.py      # single file
pytest -k "test_create"          # by name pattern
pytest --cov=moai --cov-report=term-missing  # with coverage

# Linting & formatting
ruff check src tests             # lint
ruff format src tests            # format
ruff check --fix src tests       # auto-fix
```

## Architecture

**Core flow:** Telegram command → Handler → Service → AI Orchestrator → Requesty/OpenRouter → Multiple AI APIs

```
src/moai/
├── bot/
│   ├── main.py           # Bot entry point, dispatcher setup
│   ├── handlers/         # Telegram command handlers (thin, delegate to core)
│   │   ├── projects.py   # /project commands
│   │   ├── discussion.py # /open, /discuss, @mentions
│   │   └── export.py     # /export, /consensus
│   └── middleware.py     # Auth, logging
└── core/
    ├── models.py         # SQLAlchemy models (Project, Discussion, Round, Message, Consensus)
    ├── database.py       # DB session management
    ├── orchestrator.py   # AI round management, context building, consensus detection
    ├── ai_client.py      # Requesty/OpenRouter wrapper, model routing
    └── exporter.py       # Markdown generation
```

**Key patterns:**
- Bot handlers are thin clients—business logic lives in `core/`
- Orchestrator manages discussion state: parallel (open) vs sequential (discuss) modes
- All AI calls go through `ai_client.py` which abstracts the routing layer
- SQLite for Phase 1, models designed for PostgreSQL upgrade

## Coding Standards

- **Python 3.11+**
- **Formatting:** ruff (line length 100)
- **Type hints:** Required on all public functions
- **Docstrings:** Required on modules and classes
- **Logging:** Use `logging` module, no `print()`
- **Testing:** pytest, target 80%+ coverage on core logic
- **Dependencies:** No pinned versions unless security required

## Data Model Relationships

```
Project (has many) → Discussion (has many) → Round (has many) → Message
                   ↘ Discussion (has one) → Consensus
```

## Current Phase

Phase 1: Telegram POC. Milestones:
- M1: Bot responds to /help, /status
- M2: Project CRUD
- M3-M8: Discussion modes, consensus, export, @mentions