Skip to content

Architecture.fr

Jump to bottom
WorkPilot Wiki Bot edited this page Apr 19, 2026 · 13 revisions

Architecture technique

Vue d'ensemble de l'architecture de WorkPilot AI pour les développeurs curieux ou contributeurs.

Module Chemin
backend/accessibility_agent apps/backend/accessibility_agent
backend/adversarial_qa apps/backend/adversarial_qa
backend/agent_coach apps/backend/agent_coach
backend/agents apps/backend/agents
backend/analysis apps/backend/analysis
backend/analytics apps/backend/analytics
backend/api apps/backend/api
backend/api_watcher apps/backend/api_watcher
backend/architecture apps/backend/architecture
backend/architecture_visualizer apps/backend/architecture_visualizer
backend/browser_agent apps/backend/browser_agent
backend/carbon_profiler apps/backend/carbon_profiler
backend/cli apps/backend/cli
backend/compliance_collector apps/backend/compliance_collector
backend/consensus_arbiter apps/backend/consensus_arbiter
backend/context apps/backend/context
backend/context_mesh apps/backend/context_mesh
backend/continuous_ai apps/backend/continuous_ai
backend/core apps/backend/core
backend/cost_intelligence apps/backend/cost_intelligence
backend/database_agent apps/backend/database_agent
backend/design_to_code apps/backend/design_to_code
backend/doc_drift_detector apps/backend/doc_drift_detector
backend/documentation apps/backend/documentation
backend/environment apps/backend/environment
backend/flaky_test_detective apps/backend/flaky_test_detective
backend/git_surgeon apps/backend/git_surgeon
backend/i18n_agent apps/backend/i18n_agent
backend/ideation apps/backend/ideation
backend/implementation_plan apps/backend/implementation_plan
backend/injection_guard apps/backend/injection_guard
backend/integrations apps/backend/integrations
backend/intent apps/backend/intent
backend/learning apps/backend/learning
backend/learning_loop apps/backend/learning_loop
backend/live_companion apps/backend/live_companion
backend/memory apps/backend/memory
backend/merge apps/backend/merge
backend/migration apps/backend/migration
backend/mission_control apps/backend/mission_control
backend/notebook_agent apps/backend/notebook_agent
backend/onboarding_agent apps/backend/onboarding_agent
backend/orchestration apps/backend/orchestration
backend/performance apps/backend/performance
backend/planner_lib apps/backend/planner_lib
backend/prediction apps/backend/prediction
backend/project apps/backend/project
backend/prompts apps/backend/prompts
backend/prompts_pkg apps/backend/prompts_pkg
backend/qa apps/backend/qa
backend/regression_guardian apps/backend/regression_guardian
backend/release_coordinator apps/backend/release_coordinator
backend/replay apps/backend/replay
backend/review apps/backend/review
backend/runners apps/backend/runners
backend/sandbox apps/backend/sandbox
backend/scheduling apps/backend/scheduling
backend/scripts apps/backend/scripts
backend/security apps/backend/security
backend/self_healing apps/backend/self_healing
backend/services apps/backend/services
backend/skills apps/backend/skills
backend/spec apps/backend/spec
backend/spec_refinement apps/backend/spec_refinement
backend/src apps/backend/src
backend/streaming apps/backend/streaming
backend/task_logger apps/backend/task_logger
backend/teams apps/backend/teams
backend/ui apps/backend/ui
frontend/e2e apps/frontend/e2e
frontend/resources apps/frontend/resources
frontend/scripts apps/frontend/scripts
frontend/src apps/frontend/src

🏛 Panorama global

WorkPilot AI est une application de bureau monorepo avec deux composants principaux :

┌─────────────────────────────────────────────────────────┐
│                   Electron Desktop App                   │
│  ┌──────────────────────┐    ┌────────────────────────┐ │
│  │  Renderer (React)    │◄──►│  Main Process (Node)   │ │
│  │  - Kanban UI         │IPC │  - Agent queue         │ │
│  │  - Mission Control   │    │  - Profile manager     │ │
│  │  - Terminals         │    │  - PTY daemon          │ │
│  └──────────────────────┘    └──────────┬─────────────┘ │
└───────────────────────────────────────────┼──────────────┘
                                            │ subprocess
                                            ▼
                          ┌──────────────────────────────┐
                          │    Python Backend (agents)   │
                          │  - Claude Agent SDK          │
                          │  - Planner / Coder / QA      │
                          │  - Memory (Graphiti)         │
                          │  - Integrations (GitHub...)  │
                          └──────────────────────────────┘
                                            │
                                            ▼
                          ┌──────────────────────────────┐
                          │   Worktrees (git isolés)     │
                          │   .worktrees/workpilot-ai/   │
                          └──────────────────────────────┘

Le Frontend Electron sert d'orchestrateur et d'interface. Le Backend Python contient toute la logique d'agent.

📁 Structure du monorepo

WorkPilot-AI/
├── apps/
│   ├── backend/        # Python — CLI et logique d'agents
│   └── frontend/       # Electron — application de bureau
├── src/
│   └── connectors/
│       └── grepai/     # Connecteur de recherche sémantique
├── docs/               # Documentation
├── shared_docs/        # Architecture deep dives
├── tests/              # Tests intégration transverses
└── scripts/            # Scripts build et release

🐍 Backend Python (apps/backend/)

Toute la logique d'agent vit ici.

apps/backend/
├── core/
│   ├── client.py           # create_client() — ClaudeSDKClient configuré
│   ├── auth.py             # Multi-profils OAuth
│   ├── worktree.py         # Isolation git
│   ├── platform/           # Abstraction Windows/macOS/Linux
│   └── workflow_logger.py  # Journalisation structurée
├── security/               # Allowlist, validators, hooks
├── agents/
│   ├── planner/            # Agent planificateur
│   ├── coder/              # Agent implémenteur
│   └── session/            # Gestion de session Claude SDK
├── qa/
│   ├── reviewer/           # Validation critères
│   ├── fixer/              # Résolution auto
│   ├── loop/               # Boucle Reviewer ↔ Fixer
│   └── criteria/           # Parseurs de critères
├── spec/                   # Pipeline de création de spec
├── skills/                 # Système de skills optimisé
│   ├── skill_manager.py
│   ├── context_optimizer.py
│   ├── token_optimizer.py
│   └── dynamic_skill_manager.py
├── cli/                    # Commandes CLI (spec, run, workspace, qa)
├── runners/                # 33 runners autonomes
├── context/                # Construction du contexte des tâches
├── services/               # Services transverses (recovery, etc.)
├── integrations/
│   ├── graphiti/           # Mémoire graphe
│   ├── linear/
│   ├── github/
│   └── windsurf_proxy/
├── project/                # Détection de stack, profils de sécurité
├── merge/                  # Fusion sémantique intent-aware
└── prompts/                # 37 prompts + 22 GitHub specifics

Pattern d'invocation

Toutes les interactions IA passent par le Claude Agent SDK :

from core.client import create_client
from phase_config import get_phase_model, get_phase_thinking_budget

phase_model = get_phase_model(spec_dir, "coding", cli_model=None)
phase_thinking = get_phase_thinking_budget(spec_dir, "coding", cli_thinking=None)

client = create_client(
    project_dir=project_dir,
    spec_dir=spec_dir,
    model=phase_model,
    agent_type="coder",
    max_thinking_tokens=phase_thinking,
)

async with client:
    status, response = await run_agent_session(client, prompt, spec_dir)

Règle : jamais utiliser anthropic.Anthropic() directement. Toujours create_client().

⚛️ Frontend Electron (apps/frontend/)

Stack technique

  • React 19 + TypeScript strict
  • Electron 40
  • Zustand 5 — state management (60+ stores)
  • Tailwind CSS v4 + Radix UI
  • xterm.js 6 avec WebGL
  • Vite 7 pour le bundling
  • Vitest 4 + React Testing Library
  • Biome 2 pour le lint
  • Motion (Framer Motion)

Structure

apps/frontend/src/
├── main/                    # Processus principal Electron
│   ├── agent/               # agent-queue, agent-process, agent-state, agent-events
│   ├── claude-profile/      # credential-utils, token-refresh, usage-monitor, profile-scorer
│   ├── terminal/            # pty-daemon, pty-manager, lifecycle, claude integration
│   ├── platform/            # Abstraction cross-plateforme
│   ├── ipc-handlers/        # 68 handlers par domaine
│   ├── services/            # SDK session recovery
│   └── changelog/
├── preload/                 # Bridge sécurisé main ↔ renderer
├── renderer/                # UI React
│   ├── components/
│   │   ├── onboarding/
│   │   ├── settings/
│   │   ├── task/
│   │   ├── terminal/
│   │   ├── github/
│   │   └── app-emulator/
│   ├── stores/              # 60+ Zustand stores
│   ├── contexts/            # ViewStateContext, etc.
│   ├── hooks/               # useIpc, useTerminal…
│   └── App.tsx
├── shared/
│   ├── i18n/locales/        # en/*.json, fr/*.json (55 namespaces)
│   ├── constants/           # themes.ts, etc.
│   ├── types/               # 30+ définitions TS
│   └── utils/               # ANSI sanitizer, shell escape, provider detection
└── types/

Alias TypeScript

Alias Cible
@/* src/renderer/*
@shared/* src/shared/*
@preload/* src/preload/*
@features/* src/renderer/features/*
@components/* src/renderer/shared/components/*
@hooks/* src/renderer/shared/hooks/*
@lib/* src/renderer/lib/*

Zustand stores (principaux)

Store Rôle
project-store.ts Projet actif, liste de projets
task-store.ts Tâches et specs
terminal-store.ts Sessions terminal
settings-store.ts Préférences utilisateur
github/issues-store.ts, github/pr-review-store.ts Intégration GitHub
insights-store.ts, roadmap-store.ts Vues analytics
self-healing-store.ts Incident management
pixel-office-store.ts Multi-agent Pixel Office
arena-store.ts Comparaison de modèles
mcp-marketplace-store.ts Marketplace MCP
code-migration-store.ts, design-to-code-store.ts Agents spécialisés

🔁 Cycle de vie d'une tâche

  1. Création — utilisateur crée une tâche (UI ou CLI)
  2. Spec — pipeline spec_gatherer → spec_researcher → spec_writer → spec_critic
  3. Approbation humaine (colonne Spec Review)
  4. Planning — Planner génère implementation_plan.json
  5. Coding — Coder exécute phase par phase (peut spawner sous-agents)
  6. QA Review — vérifie les critères
  7. QA Fix (si nécessaire) — boucle jusqu'à 50 itérations
  8. Human Review — utilisateur inspecte diff + preview
  9. Merge — fusion sémantique ou PR

Entre chaque étape : checkpoint persistant → reprise possible après crash.

🔒 Modèle de sécurité à 3 couches

1. Sandbox OS

Les commandes bash s'exécutent dans un environnement isolé (subprocess contrôlé avec variables d'environnement sanitizées).

2. Restrictions filesystem

Toute opération est confinée au répertoire du projet. Les chemins sont validés (core.platform.joinPaths) pour empêcher la traversée (../../).

3. Allowlist dynamique

apps/backend/security/ maintient une liste de commandes autorisées selon la stack détectée :

  • Projet Node → npm, pnpm, node, npx autorisés
  • Projet Python → pytest, python, pip, uv autorisés
  • Commandes dangereuses (rm -rf /, dd, mkfs…) systématiquement bloquées

Gestion des credentials :

  • Stockage OS : Keychain / Credential Manager / libsecret
  • Rotation OAuth automatique
  • Validation/sanitization des inputs

🌐 Multi-plateforme

Supporte Windows, macOS, Linux. La CI teste les trois.

Modules d'abstraction :

  • apps/frontend/src/main/platform/
  • apps/backend/core/platform/

Fonctions clés :

Fonction Rôle
isWindows() / isMacOS() / isLinux() Détection OS
getPathDelimiter() ; (Windows) ou : (Unix)
findExecutable(name) Lookup cross-plateforme
requiresShell(command) Détection .cmd / .bat (Windows)
joinPaths([...]) Jointure de chemin OS-agnostique

Règle : ne jamais utiliser process.platform directement.

⚡ Modèle de concurrence

Niveau Capacité
Agents parallèles Jusqu'à 12 simultanés
I/O Tout en async non-bloquant
Connexions Pooling réutilisable
Comptes IA Load balancing automatique

Optimisations

  • Compression du contexte (skills/token_optimizer.py)
  • Compactage agressif à 70 % du budget tokens (context_optimizer.py)
  • Checkpoints entre phases
  • Virtual scrolling et lazy loading côté UI
  • WebGL pour xterm.js

🌍 i18n

Toute chaîne UI doit utiliser react-i18next. 55 namespaces par langue, fichiers JSON :

  • apps/frontend/src/shared/i18n/locales/en/*.json
  • apps/frontend/src/shared/i18n/locales/fr/*.json
import { useTranslation } from 'react-i18next';
const { t } = useTranslation(['navigation', 'common']);

<span>{t('navigation:items.githubPRs')}</span>            // ✅
<span>{t('errors:task.parseError', { error })}</span>     // ✅ avec interpolation
<span>GitHub PRs</span>                                    // ❌ interdit

Nouveaux textes → ajouter les clés dans toutes les langues.

🧪 Testing

Stack Commande Outil
Backend apps/backend/.venv/bin/pytest tests/ -v pytest
Frontend unit cd apps/frontend && pnpm test Vitest
Frontend E2E cd apps/frontend && pnpm test:e2e Playwright
All backend pnpm run test:backend (depuis root) pytest

Electron MCP permet aux agents QA d'interagir avec l'app elle-même pour la self-validation :

pnpm run dev:debug
export ELECTRON_MCP_ENABLED=true
python run.py --spec 001 --qa

Outils exposés : take_screenshot, click_by_text, fill_input, get_page_structure, send_keyboard_shortcut, eval.

🔗 IPC Main ↔ Renderer

  • Handlers : src/main/ipc-handlers/ — organisés par domaine
  • Preload : src/preload/ — expose une API sécurisée
  • Pattern : renderer → window.electronAPI.* → handler main → réponse

68 modules de handlers au total (github, gitlab, ideation, context, terminal, agent…).

📡 Pour aller plus loin

  • shared_docs/ARCHITECTURE.md — deep dive complet
  • shared_docs/README.md — index des deep dives par sujet
  • apps/frontend/CONTRIBUTING.md — guide contribution frontend
  • apps/backend/skills/CLAUDE.md — règles du système de skills

Prochaine étape

➡️ Utilisation CLI pour serveurs et CI/CD

WorkPilot AI — Framework autonome multi-agents sous licence AGPL-3.0 · Dépôt · Issues · Discord

📖 WorkPilot AI Wiki

🌐 English · Français

Getting started / Pour débuter

Usage

Advanced / Avancé

Community / Communauté

🔗 Links

Clone this wiki locally