Architecture.fr

Architecture technique

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

---

🏛 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