zebra-power/CLAUDE.md

Directives Claude pour Zebra Power 🍅

Contexte du Projet

Zebra Power (nommée d'après la tomate verte zebra) est une application web dockerisée pour la gestion de serveurs via Wake-on-LAN et le contrôle de machines virtuelles Proxmox. Il s'agit d'un outil d'administration réseau légitime à usage défensif uniquement.

Architecture et Technologies

Backend (FastAPI + SQLite)

• Langages: Python 3.11+
• Framework: FastAPI 0.104.1 avec SQLAlchemy 2.0.23
• Base de données: SQLite (fichier local ./data/zebra.db)
• Services: Wake-on-LAN, API Proxmox, logging centralisé
• Point d'entrée: backend/app/main.py

Frontend (Vue.js 3)

• Framework: Vue.js 3.4.0 + Vue Router + Pinia
• Build: Vite 5.0.8
• Styling: Tailwind CSS 3.3.6
• Composants: Headless UI + Heroicons
• Point d'entrée: frontend/src/main.js

Infrastructure

• Containerisation: Docker Compose
• Proxy: Nginx (port 80)
• Réseau: Mode host pour backend (requis WOL)

Standards de Développement

Code Style

• Python: PEP 8, type hints obligatoires
• JavaScript: ESLint + Prettier
• Vue: Composition API, script setup
• CSS: Tailwind utilitaires, composants réutilisables

Structure des Fichiers

backend/app/
├── api/          # Endpoints REST
├── models/       # Schémas Pydantic + SQLAlchemy
├── services/     # Logique métier
└── main.py       # Application FastAPI

frontend/src/
├── components/   # Composants Vue réutilisables
├── views/        # Pages/routes principales
├── services/     # API client
└── main.js       # Bootstrap Vue

Commandes de Développement

Backend

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend

cd frontend
npm install
npm run dev    # Développement (port 3000)
npm run build  # Production

Docker (Production)

docker-compose up -d
docker-compose logs -f [service]
docker-compose down

Directives Spécifiques pour les Agents

🔒 Sécurité - OBLIGATOIRE

1. Usage défensif uniquement - Ne jamais créer/modifier du code malveillant
2. Wake-on-LAN légitime - Uniquement pour administration réseau autorisée
3. Proxmox management - Outils d'administration datacenter standards
4. Pas de backdoors - Aucune fonctionnalité cachée ou malveillante

📋 Bonnes Pratiques de Code

Backend Python

• Utiliser les types hints (from typing import...)
• Valider avec Pydantic pour les entrées API
• Gérer les exceptions avec FastAPI handlers
• Logger via le service centralisé (logging_service.py)
• Base de données via SQLAlchemy sessions (get_db())

Frontend Vue.js

• Composition API avec <script setup>
• Props typés avec defineProps()
• État global via Pinia stores
• Requêtes API via services/api.js
• Composants atomiques réutilisables

Docker

• Respect des ports existants (80, 3000, 8000)
• Volumes pour persistance (./data)
• Mode host obligatoire pour le backend (WOL)
• Variables d'environnement via .env ou compose

📁 Fichiers Importants

Configuration

• docker-compose.yml - Stack complète
• backend/requirements.txt - Dépendances Python
• frontend/package.json - Dépendances Node.js
• nginx/nginx.conf - Configuration proxy

Modèles de Données

• backend/app/database.py - Tables SQLAlchemy
• backend/app/models/schemas.py - Schémas Pydantic
• Toujours synchroniser modèles DB et API

API Endpoints

• backend/app/api/servers.py - Gestion serveurs WOL
• backend/app/api/wol.py - Wake-on-LAN et ping
• backend/app/api/proxmox.py - Clusters et VMs Proxmox

Services Métier

• backend/app/services/wol_service.py - Logique Wake-on-LAN
• backend/app/services/proxmox_service.py - Intégration Proxmox
• backend/app/services/logging_service.py - Journalisation

🔧 Debugging et Logs

Logs Backend

• FastAPI logs via uvicorn
• Application logs dans ActionLog table
• Exceptions catchées globalement dans main.py

Logs Frontend

• Console.log pour développement
• Error handling dans les composants Vue
• API errors via axios interceptors

Docker Logs

docker-compose logs backend
docker-compose logs frontend
docker-compose logs nginx

📊 Base de Données

Tables Principales

• servers - Serveurs Wake-on-LAN
• proxmox_clusters - Configuration clusters
• action_logs - Historique des actions
• wol_logs - Logs spécifiques WOL (legacy)

Migrations

• SQLAlchemy auto-create via init_db()
• Pas de migrations formelles (à implémenter)
• Sauvegarde manuelle de ./data/zebra.db

🌐 API et Frontend Communication

Standards API

• REST endpoints avec préfixes /api/
• Codes status HTTP standards
• JSON uniquement
• CORS permissif (à restreindre)

Client Frontend

• Axios dans services/api.js
• Base URL via variable d'environnement
• Error handling centralisé
• Loading states dans les composants

⚡ Performance

Backend

• SQLite avec pool de connexions
• Async/await pour I/O operations
• Pagination pour listes importantes

Frontend

• Lazy loading des routes Vue
• Composition API pour réactivité
• Tailwind purge pour CSS optimisé
• Vite pour build rapide

🚀 Déploiement

Développement Local

1. Clone du repo
2. mkdir -p data pour SQLite
3. docker-compose up -d
4. Interface sur http://localhost

Production

• Même stack Docker
• Variables d'environnement sécurisées
• HTTPS recommandé (nginx SSL)
• Sauvegarde régulière de ./data/

💡 Bonnes Pratiques Agents Claude

1. Toujours lire la documentation avant modification
2. Respecter l'architecture existante - pas de refactoring majeur sans validation
3. Tester les changements avec Docker Compose
4. Maintenir la cohérence - même style, mêmes patterns
5. Documenter les modifications non-triviales
6. Sécurité first - valider les entrées, gérer les erreurs
7. Performance - éviter les requêtes N+1, optimiser les queries
8. UX - interfaces intuitives, feedback utilisateur