mesh/QUICKSTART.md

<!--
Created by: Claude
Date: 2026-01-01
Purpose: Quick start guide for Mesh development
Refs: README.md, CLAUDE.md
-->

# Mesh - Guide de Démarrage Rapide

Ce guide vous permet de lancer et tester Mesh rapidement avec le chat temps réel fonctionnel.

## Prérequis

- **Docker** (recommandé pour le serveur)
- **Node.js 18+** et npm pour le client
- **Python 3.12+** (optionnel, pour développement local sans Docker)

## ⚡ Démarrage Rapide (5 minutes)

### 1. Lancer le Serveur avec Docker

```bash
cd server

# Configuration
cp .env.example .env
# Le fichier par défaut fonctionne tel quel pour les tests

# Construire et lancer
docker build -t mesh-server .
docker run -d --name mesh-server -p 8000:8000 --env-file .env mesh-server

# Vérifier que ça tourne
docker logs mesh-server
# Vous devriez voir: "Uvicorn running on http://0.0.0.0:8000"
```

### 2. Lancer le Client Web

```bash
cd client

# Configuration
cp .env.example .env
# L'URL par défaut (http://localhost:8000) fonctionne

# Installer les dépendances
npm install

# Lancer en développement
npm run dev
# Le client démarre sur http://localhost:5173

```

### 3. Tester l'Application

Ouvrir `http://localhost:5173` dans votre navigateur.

#### Premier utilisateur
1. **S'inscrire** :
   - Cliquer sur "S'inscrire"
   - Username: `alice`
   - Password: `password123`
   - Cliquer sur "S'inscrire"

2. **Créer une room** :
   - Cliquer sur "+ Nouvelle Room"
   - Nom: `Test Chat`
   - Cliquer sur "Créer"

3. **Vérifier la connexion** :
   - En bas de la sidebar, vous devriez voir "● Connecté"
   - Dans la liste des participants, vous devriez voir "alice (vous)"

4. **Envoyer un message** :
   - Tapez "Hello!" dans le champ en bas
   - Cliquer sur "Envoyer"
   - Le message apparaît immédiatement

#### Deuxième utilisateur (test multi-utilisateur)
1. Ouvrir une fenêtre de **navigation privée**
2. Aller sur `http://localhost:5173`
3. S'inscrire avec username: `bob`, password: `password123`
4. Cliquer sur la room "Test Chat" dans la liste
5. Envoyer un message
6. **Les deux utilisateurs voient les messages en temps réel!** ✨

## ✅ Tests Automatisés

### Tester l'API REST

```bash
cd server
python3 test_api.py
```

Résultat attendu : Tous les tests passent (8/8) ✓

### Tester l'API P2P

```bash
cd server
python3 test_p2p_api.py
```

Résultat attendu : Tous les tests P2P passent (5/5) ✓

## 📊 Vérifications

### Serveur en bonne santé

```bash
curl http://localhost:8000/health
# Réponse: {"status":"healthy"}
```

### Documentation API Interactive

Ouvrir dans le navigateur : `http://localhost:8000/docs`

### WebSocket Connecté

Ouvrir la console du navigateur (F12) :
```
WebSocket connected
Received peer_id: <uuid>
```

## 🔧 Option 2: Développement Local (Sans Docker)

### Serveur Python

```bash
cd server

# Environnement virtuel
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Dépendances
pip install -r requirements.txt

# Configuration
cp .env.example .env

# Lancer
python3 -m uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
```

**Note**: Python 3.13 n'est pas encore supporté. Utiliser Python 3.12 ou Docker.

### Client React

Même procédure que le démarrage rapide (étape 2).

## 🛑 Arrêter les Services

### Docker

```bash
docker rm -f mesh-server
```

### Local

Appuyer sur `Ctrl+C` dans chaque terminal.

## ⚠️ Problèmes Courants

### Port 8000 déjà utilisé

```bash
# Trouver le processus
lsof -i :8000

# Tuer le processus
kill -9 <PID>
```

### Erreur Python 3.13

➜ **Solution** : Utiliser Docker (qui utilise Python 3.12)

### WebSocket ne se connecte pas

1. Vérifier que le serveur tourne :
   ```bash
   curl http://localhost:8000/health
   ```

2. Vérifier la console du navigateur (F12) pour les erreurs

3. Vérifier le fichier `.env` du client :
   ```
   VITE_API_URL=http://localhost:8000
   ```

### Messages ne s'affichent pas

1. Ouvrir la console du navigateur (F12)
2. Vérifier : "WebSocket connected"
3. Vérifier que vous êtes dans la room (sidebar montre les participants)
4. Vérifier les logs du serveur :
   ```bash
   docker logs mesh-server -f
   ```

## 🎯 Fonctionnalités Actuelles

- ✅ **Authentification** : Login/Register fonctionnel
- ✅ **Gestion des Rooms** : Créer, lister, rejoindre
- ✅ **Chat Temps Réel** : Messages instantanés via WebSocket
- ✅ **Multi-utilisateurs** : Plusieurs utilisateurs dans la même room
- ✅ **Présence** : Voir qui est en ligne
- ✅ **Sessions P2P** : API prête pour QUIC
- ⬜ **Audio/Vidéo** : En cours de développement
- ⬜ **Partage d'écran** : En cours de développement
- ⬜ **Agent Desktop** : Pas encore démarré

## 📚 Documentation

- [CLAUDE.md](CLAUDE.md) - Instructions pour Claude Code
- [DEVELOPMENT.md](DEVELOPMENT.md) - Suivi du développement
- [docs/protocol_events_v_2.md](docs/protocol_events_v_2.md) - Protocole WebSocket
- [docs/security.md](docs/security.md) - Modèle de sécurité
- [server/CLAUDE.md](server/CLAUDE.md) - Guide serveur
- [client/CLAUDE.md](client/CLAUDE.md) - Guide client

## 🚀 Prochaines Étapes

Pour contribuer au développement :

1. Lire [DEVELOPMENT.md](DEVELOPMENT.md)
2. Choisir une tâche dans [TODO.md](TODO.md)
3. Consulter les CLAUDE.md pour les conventions
4. Utiliser les pre-commit hooks (voir [docs/tooling_precommit_vscode_snippets.md](docs/tooling_precommit_vscode_snippets.md))

# Type checking
mypy src/
```

### Agent Development

```bash
cd agent

cargo run            # Run in debug mode
cargo build          # Build debug binary
cargo build --release # Build optimized binary
cargo test           # Run tests
cargo fmt            # Format code
cargo clippy         # Lint code
```

## Pre-commit Hooks Setup

To enforce code quality and traceability headers:

```bash
# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

# Run on all files
pre-commit run --all-files
```

This will check that all new files have proper traceability headers.

## VS Code Setup

The project includes VS Code snippets for traceability headers.

**Usage**:
1. Create a new file
2. Type `mesh-header-` and select the appropriate language snippet
3. Fill in your name, description, and references

Available snippets:
- `mesh-header-py` - Python header
- `mesh-header-rs` - Rust header
- `mesh-header-ts` - TypeScript/JavaScript header
- `mesh-header-md` - Markdown header
- `mesh-header-yaml` - YAML header
- `mesh-mod` - Modified-by tag

## Testing the Stack

### 1. Check Server Health

```bash
curl http://localhost:8000/health
# Expected: {"status":"healthy"}
```

### 2. Access API Documentation

Open http://localhost:8000/docs in your browser to see FastAPI interactive docs.

### 3. Open Client

Open http://localhost:3000 in your browser. You should see the Mesh login page with a dark Monokai-inspired theme.

### 4. Check Agent

The agent should connect to the server. Check logs:

```bash
# If running with Docker
docker-compose -f infra/docker-compose.dev.yml logs agent

# If running manually
# Check terminal output where you ran `cargo run`
```

## Common Issues

### Port Already in Use

If port 8000 or 3000 is already in use:

**Server**: Change port in `.env` or command line:
```bash
python -m uvicorn src.main:app --reload --port 8001
```

**Client**: Change port in `vite.config.ts` or:
```bash
npm run dev -- --port 3001
```

### Database Error

If SQLite database is locked or corrupted:
```bash
rm server/mesh.db
# Server will recreate on next start
```

### Module Not Found (Python)

Make sure virtual environment is activated:
```bash
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
```

### Rust Compilation Errors

Update Rust to latest stable:
```bash
rustup update stable
```

### Client Build Errors

Clear cache and reinstall:
```bash
cd client
rm -rf node_modules package-lock.json
npm install
```

## Next Steps

1. **Read the documentation**:
   - [CLAUDE.md](CLAUDE.md) - Project overview and guidelines
   - [server/CLAUDE.md](server/CLAUDE.md) - Server development
   - [client/CLAUDE.md](client/CLAUDE.md) - Client development
   - [agent/CLAUDE.md](agent/CLAUDE.md) - Agent development

2. **Understand the architecture**:
   - [AGENT.md](AGENT.md) - Agent architecture
   - [security.md](security.md) - Security model
   - [protocol_events_v_2.md](protocol_events_v_2.md) - Event protocol

3. **Start developing**:
   - Create a new feature branch
   - Add traceability headers to new files
   - Follow the three-plane architecture
   - Use `/clear` between different tasks

## Stopping Services

### Docker

```bash
cd infra
docker-compose -f docker-compose.dev.yml down
# Or to remove volumes as well:
docker-compose -f docker-compose.dev.yml down -v
```

### Manual

Press `Ctrl+C` in each terminal where services are running.

---

**Happy coding!** Remember: The truth of the Mesh project is in the files, not in the conversation history.