Architecture

Architecture

🌍 English narrative is auto-generated on release. See the French version for the current full content.

High-level map of the WorkPilot AI codebase: Electron frontend, Python backend, IPC bridges, and agent orchestration.

Module	Path
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

Architecture

WorkPilot AI runs as a desktop application combining a Python backend with an Electron/React frontend, orchestrating an autonomous multi-agent pipeline: Planner → Coder → QA Reviewer → QA Fixer, followed by human review and merge. Every task executes inside an isolated git worktree, so the main branch is never touched directly; changes are reintegrated through an AI-powered semantic merge that resolves conflicts intent-aware rather than line-by-line.

Backend (apps/backend/)

The backend is Python and owns all agent logic. It has grown into 90+ specialized modules, with the core ones being:

Area	Responsibility
core/	LLM client factory (client.py, the only sanctioned entry point via the Claude Agent SDK), auth, worktree isolation, platform abstraction
agents/	Planner and coder execution logic, session management
qa/	Reviewer, fixer, and the QA validation loop
spec/	Spec creation pipeline (complexity assessment → specification)
runners/	~66 standalone entry points (spec, GitHub, Azure DevOps, self-healing, etc.)
merge/	Intent-aware semantic merge
integrations/	Graphiti memory, GitHub/GitLab, Linear, Windsurf
prompts/	60+ system prompts, one per specialized agent

A declarative workflow engine (workflows/) resolves a build's phases against the user's chosen effort level, the provider's capabilities, and the files touched, printing the resolved profile before the build starts.

Frontend (apps/frontend/)

An Electron application with a React 19 + TypeScript renderer. The main process manages agent queues, Claude profile credentials, PTY-based terminals, and 100+ domain-organized IPC handlers; the renderer holds the Kanban board, terminals, and settings UI backed by ~96 Zustand stores; a preload layer bridges the two via a safe electronAPI.

Execution Flow

Task creation → spec generation → planning → parallel-capable coding → QA validation → issue resolution → merge. State is tracked across dedicated stores (project, task/spec, terminal, agent, settings), giving real-time visibility into each phase.

Security & Isolation

A three-layer model governs agent actions: OS-level sandboxing of Bash commands, filesystem restrictions to the project directory, and a dynamic command allowlist derived from the detected project stack. Credentials use OS-native secure storage (Keychain / Credential Manager) with automatic OAuth token rotation.

---

➡️ Continue: CLI usage