# 🦊 Foxy Dev Team
### Département de Développement Logiciel Autonome
*Une équipe d'agents IA spécialisés, orchestrés pour transformer vos besoins en logiciels fonctionnels — de la conception au déploiement.*
[](#)
[](#)
[](#)
[](#)
[](#)
[](#-licence)
---
## 📋 Table des Matières
- [Vision](#-vision)
- [Architecture v2.0](#-architecture-v20)
- [Les Agents de la Team](#-les-agents-de-la-team)
- [Workflows](#-workflows)
- [Prérequis](#-prérequis)
- [Installation](#-installation)
- [Déploiement Docker](#-déploiement-docker)
- [Configuration](#-configuration)
- [Structure du Projet](#-structure-du-projet)
- [API Reference](#-api-reference)
- [Dashboard](#-dashboard)
- [Telegram Bot](#-telegram-bot)
- [Gestion des Services](#-gestion-des-services-systemd)
- [Sécurité](#%EF%B8%8F-sécurité--conformité)
- [Contribution](#-contribution)
- [Licence](#-licence)
---
## 🎯 Vision
Foxy Dev Team est un département de développement logiciel **complet et entièrement automatisé**, dirigé par 6 agents IA spécialisés. Le système orchestre la totalité du cycle de vie logiciel — analyse des besoins, architecture, développement, tests, et déploiement.
### Pourquoi v2.0 ?
La v1.0 utilisait un daemon (`foxy-autopilot.py`) et un fichier `project_state.json` local. La v2.0 remplace entièrement cette approche par :
| v1.0 (Ancien) | v2.0 (Nouveau) |
|---|---|
| Fichier `project_state.json` | Base de données SQLite (async) |
| Daemon poll / `fcntl` PID lock | FastAPI async + WebSocket |
| Subprocess bloquants | `asyncio.create_subprocess_exec` |
| Un seul projet à la fois | Multi-projets simultanés |
| Pas de dashboard | Dashboard React temps réel |
| Telegram direct subprocess | Bot Telegram v3 via API |
| Secrets hardcodés | `.env` + `pydantic-settings` |
---
## 🏗️ Architecture v2.0
```
┌─────────────────────────────────────────────────────────────────┐
│ 🌐 Navigateur / Dashboard │
│ React 19 + TypeScript + TailwindCSS v4 │
└───────────────────────────┬─────────────────────────────────────┘
│ HTTP REST + WebSocket
┌───────────────────────────┴─────────────────────────────────────┐
│ 🦊 FastAPI Backend │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────────┐ │
│ │ Projects │ │ Agents │ │ Logs │ │ WebSocket Hub │ │
│ │ API │ │ API │ │ API │ │ (temps réel) │ │
│ └─────┬────┘ └─────┬────┘ └─────┬────┘ └────────┬───────────┘ │
│ └─────────────┼───────────┘ │ │
│ ┌───────┴────────┐ │ │
│ │ SQLAlchemy │ ┌──────────────┤ │
│ │ (async ORM) │ │ Workflow │ │
│ └───────┬────────┘ │ Engine │ │
│ │ └──────────────┘ │
│ ┌───────┴────────┐ │
│ │ SQLite DB │ │
│ └────────────────┘ │
│ │
│ ┌────────────────┐ ┌───────────────────┐ │
│ │ OpenClaw CLI │ │ Telegram Notifs │ │
│ │ Integration │ │ (httpx async) │ │
│ └────────────────┘ └───────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
│
┌───────────────────────────┴─────────────────────────────────────┐
│ 🤖 Telegram Bot v3 │
│ Consomme l'API centralisée (plus de subprocess) │
└─────────────────────────────────────────────────────────────────┘
```
---
## 👥 Les Agents de la Team
| Agent | Rôle | Modèle | Spécialité |
|---|---|---|---|
| **[Foxy-Conductor](./AGENT-01-CONDUCTOR.md)** 🎼 | Chef d'orchestre | `grok-4.1-fast` | Coordination, planification |
| **[Foxy-Architect](./AGENT-02-ARCHITECT.md)** 🏗️ | Architecte système | `grok-4.1-fast` | Conception technique, specs |
| **[Foxy-Dev](./AGENT-03-DEV.md)** 💻 | Développeur Backend | `minimax-m2.5` | Code backend, APIs |
| **[Foxy-UIUX](./AGENT-04-UIUX.md)** 🎨 | Designer & Frontend | `qwen3-30b-a3b` | UI/UX, composants |
| **[Foxy-QA](./AGENT-05-QA.md)** 🔍 | Gardien de la qualité | `qwen3.5-flash` | Tests, audit sécurité |
| **[Foxy-Admin](./AGENT-06-ADMIN.md)** 🚀 | DevOps & Déploiement | `grok-4.1-fast` | Infrastructure, deploy |
Chaque agent dispose de sa propre documentation détaillée (`AGENT-*.md`) décrivant son rôle, ses workflows, ses standards, et ses formats de communication.
---
## 🔄 Workflows
Le moteur de workflows v2.0 supporte **4 types de projets** avec routage dynamique des agents :
### 🏗️ SOFTWARE_DESIGN — Conception logicielle complète
```
Conductor → Architect → Dev → UIUX → QA → Admin (Deploy)
```
### 🐛 SYSADMIN_DEBUG — Débogage Sysadmin
```
Conductor → Admin (Diagnostic & Fix) → QA (Validation)
```
### 🐳 DEVOPS_SETUP — Configuration DevOps
```
Conductor → Admin (Setup infra) → QA (Validation)
```
### 🔧 SYSADMIN_ADJUST — Ajustement Sysadmin
```
Conductor → Admin (Ajustements) → QA (Validation)
```
---
## 📦 Prérequis
| Composant | Version minimum | Utilisation |
|---|---|---|
| Python | 3.12+ | Backend FastAPI |
| Node.js | 20+ | Frontend React |
| npm | 10+ | Gestionnaire de paquets |
| Docker | 24+ | Déploiement conteneurisé (optionnel) |
| Docker Compose | 2.20+ | Orchestration Docker (optionnel) |
| OpenClaw | Latest | Orchestrateur d'agents |
---
## 🚀 Installation
### Installation rapide (Développement)
```bash
# 1. Cloner le dépôt
git clone https://git.dracodev.net/Projets/foxy-dev-team.git
cd foxy-dev-team
# 2. Backend
cd backend
cp .env.example .env # ⚠️ Éditer avec vos valeurs !
pip install -r requirements.txt
python -m uvicorn app.main:app --port 7000 --reload
# 3. Frontend (nouveau terminal)
cd frontend
npm install
npm run dev # → http://localhost:5173
# 4. Telegram Bot (optionnel, nouveau terminal)
cd scripts
export TELEGRAM_BOT_TOKEN="..." TELEGRAM_CHAT_ID="..."
python3 foxy-telegram-bot-v3.py
```
### Installation services (Production Linux)
```bash
# Installer les services systemd (user mode)
chmod +x scripts/install-services.sh
./scripts/install-services.sh
# Vérifier l'état
systemctl --user status foxy-api
systemctl --user status foxy-telegram
# Suivre les logs
journalctl --user -u foxy-api -f
journalctl --user -u foxy-telegram -f
```
### Désinstallation des services
```bash
chmod +x scripts/uninstall-services.sh
./scripts/uninstall-services.sh
```
---
## 🐳 Déploiement Docker
### Build & Run (Docker Compose)
```bash
# Configurer l'environnement
cp backend/.env.example backend/.env
# ⚠️ Éditer backend/.env avec vos valeurs réelles
# Construire et démarrer tous les services
docker compose up -d --build
# Suivre les logs
docker compose logs -f
# Arrêter
docker compose down
```
### Build manuel (image unique)
```bash
# Construire l'image (backend + frontend)
docker build -t foxy-dev-team .
# Exécuter
docker run -d \
--name foxy-api \
-p 7000:7000 \
--env-file backend/.env \
foxy-dev-team
# Construire et exécuter le bot Telegram
docker build -t foxy-telegram -f Dockerfile.telegram .
docker run -d \
--name foxy-telegram \
--env-file backend/.env \
-e FOXY_API_URL=http://foxy-api:7000 \
--network container:foxy-api \
foxy-telegram
```
### Services Docker
| Service | Image | Port | Description |
|---|---|---|---|
| `foxy-api` | `Dockerfile` | `7000` | Backend + Frontend statique |
| `foxy-telegram` | `Dockerfile.telegram` | — | Bot Telegram (API-backed) |
Le `Dockerfile` principal utilise un **build multi-stage** :
1. **Stage 1** (`node:22-alpine`) — Build frontend React
2. **Stage 2** (`python:3.12-slim`) — Runtime Python avec les assets frontend intégrés
---
## ⚙️ Configuration
### Variables d'environnement
Toute la configuration passe par le fichier `backend/.env`. Un template est fourni dans `backend/.env.example`.
| Variable | Description | Requis |
|---|---|---|
| `DATABASE_URL` | URL de la base de données | Non (défaut : SQLite) |
| `TELEGRAM_BOT_TOKEN` | Token du bot Telegram | Pour le bot |
| `TELEGRAM_CHAT_ID` | ID du chat Telegram autorisé | Pour le bot |
| `OPENCLAW_WORKSPACE` | Répertoire workspace OpenClaw | Oui |
| `GITEA_SERVER` | URL du serveur Gitea | Oui |
| `GITEA_OPENCLAW_TOKEN` | Token API Gitea | Oui |
| `DEPLOYMENT_SERVER` | Serveur de déploiement | Pour Admin |
| `DEPLOYMENT_USER` | Utilisateur SSH déploiement | Pour Admin |
| `DEPLOYMENT_PWD` | Mot de passe SSH déploiement | Pour Admin |
| `CORS_ORIGINS` | Origines CORS autorisées | Non (défaut : `*`) |
| `LOG_LEVEL` | Niveau de log (`debug`, `info`, `warning`) | Non (défaut : `info`) |
> **⚠️ Important** : Ne commitez **jamais** le fichier `.env` ! Il est exclu par `.gitignore`.
---
## 📁 Structure du Projet
```
foxy-dev-team/
├── 📋 README.md # Ce fichier
├── 📋 AGENT-01-CONDUCTOR.md # Documentation Foxy-Conductor
├── 📋 AGENT-02-ARCHITECT.md # Documentation Foxy-Architect
├── 📋 AGENT-03-DEV.md # Documentation Foxy-Dev
├── 📋 AGENT-04-UIUX.md # Documentation Foxy-UIUX
├── 📋 AGENT-05-QA.md # Documentation Foxy-QA
├── 📋 AGENT-06-ADMIN.md # Documentation Foxy-Admin
├── 🐳 Dockerfile # Multi-stage (frontend + backend)
├── 🐳 Dockerfile.telegram # Image bot Telegram
├── 🐳 docker-compose.yml # Orchestration complète
├── 🚫 .gitignore # Exclusions Git
│
├── backend/ # 🐍 Backend FastAPI
│ ├── .env.example # Template variables d'environnement
│ ├── requirements.txt # Dépendances Python
│ └── app/
│ ├── __init__.py
│ ├── main.py # Point d'entrée FastAPI
│ ├── config.py # Gestion configuration (pydantic-settings)
│ ├── database.py # Engine SQLAlchemy async
│ ├── models.py # Modèles ORM (Project, Task, etc.)
│ ├── schemas.py # Schemas Pydantic (API I/O)
│ ├── workflows.py # Moteur de workflows dynamique
│ ├── notifications.py # Service notifications Telegram
│ ├── openclaw.py # Intégration OpenClaw CLI
│ └── routers/
│ ├── __init__.py
│ ├── projects.py # CRUD projets + contrôle workflow
│ ├── agents.py # Status et historique agents
│ ├── logs.py # Audit logs filtrables
│ ├── workflows.py # Définitions workflows
│ ├── config.py # Configuration API (secrets masqués)
│ └── ws.py # WebSocket hub temps réel
│
├── frontend/ # ⚛️ Frontend React
│ ├── package.json # Dépendances npm
│ ├── vite.config.ts # Configuration Vite + proxy API
│ ├── tsconfig.json # Configuration TypeScript
│ ├── index.html # Point d'entrée HTML
│ └── src/
│ ├── main.tsx # Bootstrap React
│ ├── App.tsx # Layout + routing
│ ├── index.css # Design system (fox-orange, glass)
│ ├── vite-env.d.ts
│ ├── api/
│ │ ├── client.ts # Client API typé
│ │ └── useWebSocket.ts # Hook WebSocket (auto-reconnect)
│ └── pages/
│ ├── Dashboard.tsx # Vue d'ensemble
│ ├── Projects.tsx # Gestion projets
│ ├── Agents.tsx # Status agents temps réel
│ ├── Logs.tsx # Logs d'audit
│ └── Settings.tsx # Configuration + workflows
│
├── scripts/ # 🔧 Scripts opérationnels
│ ├── foxy-autopilot.py # [Legacy] Ancien daemon v1
│ ├── foxy-telegram-bot.py # [Legacy] Ancien bot v1
│ ├── foxy-telegram-bot-v3.py # Bot Telegram v3 (API-backed)
│ ├── install-services.sh # Installeur services systemd
│ └── uninstall-services.sh # Désinstalleur services systemd
│
└── config/
└── auto-pilot.yaml # Configuration agents OpenClaw
```
---
## 📡 API Reference
Base URL : `http://localhost:7000`
### Health
| Méthode | Endpoint | Description |
|---|---|---|
| `GET` | `/api/health` | Vérification de l'état du service |
### Projets
| Méthode | Endpoint | Description |
|---|---|---|
| `GET` | `/api/projects` | Lister tous les projets |
| `POST` | `/api/projects` | Créer un nouveau projet |
| `GET` | `/api/projects/{id}` | Détail d'un projet (+ tâches, logs) |
| `POST` | `/api/projects/{id}/start` | Démarrer / reprendre un workflow |
| `POST` | `/api/projects/{id}/pause` | Mettre en pause |
| `POST` | `/api/projects/{id}/stop` | Arrêter (marquer FAILED) |
| `POST` | `/api/projects/{id}/reset` | Réinitialiser à AWAITING_CONDUCTOR |
| `DELETE` | `/api/projects/{id}` | Supprimer un projet |
| `GET` | `/api/projects/{id}/progress` | Progression du workflow |
### Agents
| Méthode | Endpoint | Description |
|---|---|---|
| `GET` | `/api/agents` | État actuel de tous les agents |
| `GET` | `/api/agents/{name}/history` | Historique d'exécution d'un agent |
### Logs & Workflows
| Méthode | Endpoint | Description |
|---|---|---|
| `GET` | `/api/logs` | Audit logs (filtres : `project_id`, `agent`, `action`) |
| `GET` | `/api/workflows` | Définitions des 4 workflows |
| `GET` | `/api/config` | Configuration courante (secrets masqués) |
| `PUT` | `/api/config` | Mettre à jour la configuration |
### WebSocket
| Endpoint | Description |
|---|---|
| `ws://host:7000/ws/live` | Temps réel : `agent_status`, `log`, `project_update` |
> 📖 Documentation interactive Swagger : `http://localhost:7000/docs`
---
## 📊 Dashboard
Le dashboard web est accessible sur `http://localhost:5173` (dev) ou intégré dans le build Docker.
### Pages
| Page | Fonctionnalités |
|---|---|
| **Dashboard** | Stat cards, projets actifs avec barres de progression, grille agents, activité récente |
| **Projets** | Liste complète, création de projets, contrôle de flux (start/pause/stop/reset) |
| **Agents** | 6 cartes agents avec modèle IA, statistiques (total/succès/échecs), taux de succès |
| **Logs** | Table d'audit temps réel, filtres par agent, auto-scroll |
| **Config** | Édition des paramètres, visualisation des workflows disponibles |
### Design
- Thème sombre avec accents fox-orange (`#FF6D00`)
- Glassmorphism + micro-animations
- WebSocket auto-reconnect pour mises à jour temps réel
- Responsive desktop
---
## 🤖 Telegram Bot
Le bot Telegram v3 (`foxy-telegram-bot-v3.py`) interagit exclusivement via l'API centralisée.
### Commandes disponibles
| Commande | Description |
|---|---|
| `/start` | Message de bienvenue |
| `/projets` | Statut de tous les projets avec barres de progression |
| `/agents` | État des 6 agents |
| `/nouveau nom \| description` | Créer un nouveau projet |
| `/test` | Lancer un projet de test pipeline |
| `/reset [id]` | Réinitialiser un projet (ou tous) |
| `/aide` | Aide complète |
### Configuration
```bash
export TELEGRAM_BOT_TOKEN="votre_token"
export TELEGRAM_CHAT_ID="votre_chat_id"
export FOXY_API_URL="http://localhost:7000" # URL de l'API backend
```
---
## 🔧 Gestion des Services (systemd)
### Installer les services
```bash
chmod +x scripts/install-services.sh
./scripts/install-services.sh
```
Cela crée 2 services systemd (user mode) :
| Service | Description | Dépendance |
|---|---|---|
| `foxy-api` | Backend FastAPI (port 7000) | — |
| `foxy-telegram` | Bot Telegram v3 | `foxy-api` |
### Commandes de gestion
```bash
# Status
systemctl --user status foxy-api
systemctl --user status foxy-telegram
# Redémarrer
systemctl --user restart foxy-api
# Arrêter
systemctl --user stop foxy-api foxy-telegram
# Logs en temps réel
journalctl --user -u foxy-api -f
journalctl --user -u foxy-telegram -f
```
### Désinstaller
```bash
./scripts/uninstall-services.sh
```
---
## 🛡️ Sécurité & Conformité
### Principes
1. **Zéro secret en clair** — Toute configuration sensible via `.env` (exclu du Git)
2. **Masquage API** — Les tokens et mots de passe sont masqués (`***`) dans les réponses `/api/config`
3. **Audit trail complet** — Chaque action est journalisée dans `audit_log` avec timestamp, agent, et source
4. **Rollback automatique** — Foxy-Admin crée un backup avant chaque déploiement
5. **Review obligatoire** — Tout code passe par Foxy-QA avant intégration
6. **Least Privilege** — Chaque agent n'a accès qu'aux variables dont il a besoin
7. **Container non-root** — Les images Docker tournent avec un utilisateur `foxy` dédié
### Variables sensibles
| Variable | Risque | Protection |
|---|---|---|
| `TELEGRAM_BOT_TOKEN` | Contrôle du bot | `.env` + masquage API |
| `GITEA_OPENCLAW_TOKEN` | Accès aux dépôts | `.env` + masquage API |
| `DEPLOYMENT_PWD` | Accès SSH serveur | `.env` + masquage API |
---
## 🤝 Contribution
### Ajouter un nouvel agent
1. Créer `AGENT-07-[NOM].md` avec rôle, modèle, et workflow
2. Ajouter l'agent dans `backend/app/workflows.py` (registre + labels + models)
3. Mettre à jour `backend/app/openclaw.py` (labels)
4. Mettre à jour ce README
### Ajouter un nouveau workflow
1. Définir le workflow dans `backend/app/models.py` (enum `WorkflowType`)
2. Ajouter la séquence d'étapes dans `backend/app/workflows.py` (`WORKFLOW_REGISTRY`)
3. Tester via l'API : `POST /api/projects` avec le nouveau type
### Stack technique
| Couche | Technologie | Version |
|---|---|---|
| Backend | Python + FastAPI | 3.12+ / 0.115+ |
| ORM | SQLAlchemy (async) | 2.0+ |
| Base de données | SQLite (aiosqlite) | — |
| Frontend | React + TypeScript | 19 |
| CSS | TailwindCSS | v4 |
| Build | Vite | 6 |
| HTTP client | httpx | 0.28+ |
| Container | Docker (multi-stage) | 24+ |
---
## 📜 Licence
Foxy Dev Team est un projet **OpenClaw**.
**Créateurs** :
- Concept original et architecture : **Bruno Charest**
- Documentation et specs : **LUMINA** (avec contribution Foxy Dev Team agents)
**Technologies** :
- Agents spécialisés : Modèles LLM via OpenRouter
- Orchestration : OpenClaw CLI et framework
---
**🦊 Foxy Dev Team — Transformons vos idées en réalité.**
*Version 2.0.0 — Mars 2026*