mesh/QUICKSTART.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

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

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

cd server
python3 test_api.py

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

Tester l'API P2P

cd server
python3 test_p2p_api.py

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

📊 Vérifications

Serveur en bonne santé

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

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

docker rm -f mesh-server

Local

Appuyer sur Ctrl+C dans chaque terminal.

⚠️ Problèmes Courants

Port 8000 déjà utilisé

# 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 :

   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 :

   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 - Instructions pour Claude Code
• DEVELOPMENT.md - Suivi du développement
• docs/protocol_events_v_2.md - Protocole WebSocket
• docs/security.md - Modèle de sécurité
• server/CLAUDE.md - Guide serveur
• client/CLAUDE.md - Guide client

🚀 Prochaines Étapes

Pour contribuer au développement :

1. Lire DEVELOPMENT.md
2. Choisir une tâche dans TODO.md
3. Consulter les CLAUDE.md pour les conventions
4. Utiliser les pre-commit hooks (voir 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:

# 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

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:

# 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:

python -m uvicorn src.main:app --reload --port 8001

Client: Change port in vite.config.ts or:

npm run dev -- --port 3001

Database Error

If SQLite database is locked or corrupted:

rm server/mesh.db
# Server will recreate on next start

Module Not Found (Python)

Make sure virtual environment is activated:

source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

Rust Compilation Errors

Update Rust to latest stable:

rustup update stable

Client Build Errors

Clear cache and reinstall:

cd client
rm -rf node_modules package-lock.json
npm install

Next Steps

1. Read the documentation:

   • CLAUDE.md - Project overview and guidelines
   • server/CLAUDE.md - Server development
   • client/CLAUDE.md - Client development
   • agent/CLAUDE.md - Agent development

2. Understand the architecture:

   • AGENT.md - Agent architecture
   • security.md - Security model
   • 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

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.