Skip to content

Architecture.fr

Jump to bottom
WorkPilot Wiki Bot edited this page Sep 9, 2026 · 12 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/agent_endpoints apps/backend/agent_endpoints
backend/agent_health apps/backend/agent_health
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_drift apps/backend/architecture_drift
backend/architecture_visualizer apps/backend/architecture_visualizer
backend/audit_trail apps/backend/audit_trail
backend/bounty_board apps/backend/bounty_board
backend/browser_agent apps/backend/browser_agent
backend/carbon_profiler apps/backend/carbon_profiler
backend/cicd_anomaly apps/backend/cicd_anomaly
backend/cli apps/backend/cli
backend/code_playground apps/backend/code_playground
backend/cognitive_context apps/backend/cognitive_context
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/dashboard apps/backend/dashboard
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/domain_agents apps/backend/domain_agents
backend/environment apps/backend/environment
backend/event_hooks apps/backend/event_hooks
backend/flaky_test_detective apps/backend/flaky_test_detective
backend/generational_tests apps/backend/generational_tests
backend/git_surgeon apps/backend/git_surgeon
backend/hooks apps/backend/hooks
backend/i18n_agent apps/backend/i18n_agent
backend/i18n_scaler apps/backend/i18n_scaler
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/libdocs apps/backend/libdocs
backend/license_governance apps/backend/license_governance
backend/live_companion apps/backend/live_companion
backend/longevity apps/backend/longevity
backend/mem_search apps/backend/mem_search
backend/memory apps/backend/memory
backend/merge apps/backend/merge
backend/migration apps/backend/migration
backend/mission_control apps/backend/mission_control
backend/mobile apps/backend/mobile
backend/model_router apps/backend/model_router
backend/notebook_agent apps/backend/notebook_agent
backend/onboarding_agent apps/backend/onboarding_agent
backend/orchestration apps/backend/orchestration
backend/pair_realtime apps/backend/pair_realtime
backend/parallel_variations apps/backend/parallel_variations
backend/performance apps/backend/performance
backend/planner_lib apps/backend/planner_lib
backend/prediction apps/backend/prediction
backend/progress_indicator apps/backend/progress_indicator
backend/project apps/backend/project
backend/prompts apps/backend/prompts
backend/prompts_pkg apps/backend/prompts_pkg
backend/qa apps/backend/qa
backend/qa_promotion apps/backend/qa_promotion
backend/regression_guardian apps/backend/regression_guardian
backend/release_coordinator apps/backend/release_coordinator
backend/replay apps/backend/replay
backend/restart_planner apps/backend/restart_planner
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/server apps/backend/server
backend/services apps/backend/services
backend/skills apps/backend/skills
backend/skills_registry apps/backend/skills_registry
backend/slash_commands apps/backend/slash_commands
backend/spec apps/backend/spec
backend/spec_refinement apps/backend/spec_refinement
backend/src apps/backend/src
backend/streaming apps/backend/streaming
backend/system_status apps/backend/system_status
backend/task_logger apps/backend/task_logger
backend/teams apps/backend/teams
backend/tech_debt apps/backend/tech_debt
backend/test_generation apps/backend/test_generation
backend/timeline apps/backend/timeline
backend/ui apps/backend/ui
backend/virtual_reviewer apps/backend/virtual_reviewer
backend/workflows apps/backend/workflows
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/*
@renderer/* src/renderer/components/*
@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