Mikkel Georgsen
9651bd4166
- CLAUDE.md provides guidance for Claude Code with build commands, architecture overview, and coding standards from SPEC.md - .gitignore covers Python, virtual envs, testing, IDE files, and env files Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
79 lines
2.8 KiB
Markdown
79 lines
2.8 KiB
Markdown
# 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
|