🦊 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.

---

📋 Table des Matières

• Vision
• Architecture v2.0
• Les Agents de la Team
• Workflows
• Prérequis
• Installation
• Déploiement Docker
• Configuration
• Structure du Projet
• API Reference
• Dashboard
• Telegram Bot
• Gestion des Services
• Sécurité
• Contribution
• 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 🎼	Chef d'orchestre	grok-4.1-fast	Coordination, planification
Foxy-Architect 🏗️	Architecte système	grok-4.1-fast	Conception technique, specs
Foxy-Dev 💻	Développeur Backend	minimax-m2.5	Code backend, APIs
Foxy-UIUX 🎨	Designer & Frontend	qwen3-30b-a3b	UI/UX, composants
Foxy-QA 🔍	Gardien de la qualité	qwen3.5-flash	Tests, audit sécurité
Foxy-Admin 🚀	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)

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

# 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

chmod +x scripts/uninstall-services.sh
./scripts/uninstall-services.sh

---

🐳 Déploiement Docker

Build & Run (Docker Compose)

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

# 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

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

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

# 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

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