# pypilot-dev/pypilot-vscode architecture

> Architecture diagram of the GitHub repository pypilot-dev/pypilot-vscode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pypilot-dev/pypilot-vscode
- Repository: https://github.com/pypilot-dev/pypilot-vscode

## Overview

PyPilot is a VS Code extension that coordinates a native PyPilot engine per Python workspace. The main workflow is activation and helper resolution, project/server setup, user-triggered diagnosis or environment changes, and presentation of status or a doctor report. The README also documents engine capabilities such as Python-version and CUDA matching, import diagnostics, and pixi support. Several of those engine internals are not in this repository; they are represented as documented capabilities, not inspected implementation. Links reflect sampled source references or README statements.

Main entry points: [`src/extension.ts`](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/extension.ts) (Extension Activation), [`src/commands.ts`](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/commands.ts) (Command Handlers), [`src/downloader.ts`](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/downloader.ts) (Helper Resolution), [`src/venv.ts`](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/venv.ts) (Interpreter Selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_activation["Activation and Engine"]
  node_extension["Extension Activation<br/>[extension.ts]"]
  node_helper["Helper Resolution<br/>[downloader.ts]"]
  node_transport["Download Transport<br/>[net.ts]"]
  node_installer["Helper Installer<br/>[helperInstall.ts]"]
  node_engine_checks["Engine Version Checks<br/>[engine.ts]"]
end

subgraph group_workspace["Workspace Integration"]
  node_clients["Workspace Language Clients<br/>[clients.ts]"]
  node_commands["Command Handlers<br/>[commands.ts]"]
  node_tasks["Workspace Tasks<br/>[tasks.ts]"]
  node_status["Status Bar<br/>[statusBar.ts]"]
end

subgraph group_diagnostics["Project Diagnosis"]
  node_doctor["Doctor and Fixes"]
  node_version_match["Python Version Resolution"]
  node_hardware["CUDA and Driver Matching"]
  node_imports["Import Diagnostics"]
  node_report["Report Coordination<br/>[report.ts]"]
  node_panel["Interactive Report Panel<br/>[reportPanel.ts]"]
end

subgraph group_environment["Environment Management"]
  node_project["Project Detection<br/>[project.ts]"]
  node_venv["Interpreter Selection<br/>[venv.ts]"]
end

node_developer(("Python Developer"))
node_vscode["VS Code"]
node_engine["Native PyPilot Engine"]
node_python_api["Python Extension API"]

node_developer -->|"uses"| node_vscode
node_vscode -->|"activates"| node_extension
node_extension -->|"starts selection"| node_venv
node_extension -->|"resolves helper"| node_helper
node_helper -->|"downloads through"| node_transport
node_helper -->|"checks versions"| node_engine_checks
node_helper -->|"installs with"| node_installer
node_helper -->|"locates or downloads"| node_engine
node_extension -->|"starts clients"| node_clients
node_clients -->|"runs per project"| node_engine
node_extension -->|"registers"| node_commands
node_extension -->|"registers"| node_tasks
node_extension -->|"initializes"| node_report
node_commands -->|"selects client"| node_clients
node_commands -->|"updates"| node_status
node_commands -->|"checks project"| node_project
node_commands -->|"checks environment"| node_venv
node_status -->|"reads manager"| node_project
node_status -->|"reads environment"| node_venv
node_venv -->|"selects interpreter via"| node_python_api
node_project -->|"detects pixi through"| node_venv
node_engine -->|"produces diagnosis and fixes"| node_doctor
node_engine -->|"resolves supported versions"| node_version_match
node_engine -->|"matches CUDA wheels"| node_hardware
node_engine -->|"checks imports"| node_imports
node_report -->|"requests details from"| node_clients
node_report -->|"shows report in"| node_panel
node_panel -->|"exports or copies"| node_vscode
node_developer -->|"runs commands"| node_commands
node_developer -->|"runs tasks"| node_tasks
node_developer -->|"views report"| node_panel

click node_extension "https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/extension.ts"
click node_helper "https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/downloader.ts"
click node_transport "https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/net.ts"
click node_installer "https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/helperInstall.ts"
click node_engine_checks "https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/engine.ts"
click node_clients "https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/clients.ts"
click node_commands "https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/commands.ts"
click node_tasks "https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/tasks.ts"
click node_status "https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/statusBar.ts"
click node_project "https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/project.ts"
click node_venv "https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/venv.ts"
click node_report "https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/report.ts"
click node_panel "https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/webview/reportPanel.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension,node_helper,node_transport,node_installer,node_engine_checks toneBlue
class node_clients,node_commands,node_tasks,node_status toneAmber
class node_doctor,node_version_match,node_hardware,node_imports,node_report,node_panel,node_python_api toneMint
class node_project,node_venv toneRose
class node_developer,node_vscode,node_engine toneIndigo
```

## Components

### Activation and Engine

- [Extension Activation](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/extension.ts): `src/extension.ts`
- [Helper Resolution](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/downloader.ts): `src/downloader.ts`
- [Download Transport](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/net.ts): `src/net.ts`
- [Helper Installer](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/helperInstall.ts): `src/helperInstall.ts`
- [Engine Version Checks](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/engine.ts): `src/engine.ts`

### Workspace Integration

- [Workspace Language Clients](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/clients.ts): `src/clients.ts`
- [Command Handlers](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/commands.ts): `src/commands.ts`
- [Workspace Tasks](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/tasks.ts): `src/tasks.ts`
- [Status Bar](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/statusBar.ts): `src/statusBar.ts`

### Project Diagnosis

- **Doctor and Fixes**
- **Python Version Resolution**
- **CUDA and Driver Matching**
- **Import Diagnostics**
- [Report Coordination](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/report.ts): `src/report.ts`
- [Interactive Report Panel](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/webview/reportPanel.ts): `src/webview/reportPanel.ts`

### Environment Management

- [Project Detection](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/project.ts): `src/project.ts`
- [Interpreter Selection](https://github.com/pypilot-dev/pypilot-vscode/blob/master/src/venv.ts): `src/venv.ts`

### Other components

- **Python Developer**
- **VS Code**
- **Native PyPilot Engine**
- **Python Extension API**

## Connections

- Python Developer → VS Code: uses (evidence: `README.md`)
- VS Code → Extension Activation: activates (evidence: `src/extension.ts`)
- Extension Activation → Interpreter Selection: starts selection (evidence: `src/extension.ts`)
- Extension Activation → Helper Resolution: resolves helper (evidence: `src/extension.ts`)
- Helper Resolution → Download Transport: downloads through (evidence: `src/downloader.ts`)
- Helper Resolution → Engine Version Checks: checks versions (evidence: `src/downloader.ts`)
- Helper Resolution → Helper Installer: installs with (evidence: `src/downloader.ts`)
- Helper Resolution → Native PyPilot Engine: locates or downloads (evidence: `src/downloader.ts`)
- Extension Activation → Workspace Language Clients: starts clients (evidence: `src/extension.ts`)
- Workspace Language Clients → Native PyPilot Engine: runs per project (evidence: `src/clients.ts`)
- Extension Activation → Command Handlers: registers (evidence: `src/extension.ts`)
- Extension Activation → Workspace Tasks: registers (evidence: `src/extension.ts`)
- Extension Activation → Report Coordination: initializes (evidence: `src/extension.ts`)
- Command Handlers → Workspace Language Clients: selects client (evidence: `src/commands.ts`)
- Command Handlers → Status Bar: updates (evidence: `src/commands.ts`)
- Command Handlers → Project Detection: checks project (evidence: `src/commands.ts`)
- Command Handlers → Interpreter Selection: checks environment (evidence: `src/commands.ts`)
- Status Bar → Project Detection: reads manager (evidence: `src/statusBar.ts`)
- Status Bar → Interpreter Selection: reads environment (evidence: `src/statusBar.ts`)
- Interpreter Selection → Python Extension API: selects interpreter via (evidence: `src/venv.ts`)
- Project Detection → Interpreter Selection: detects pixi through (evidence: `src/project.ts`)
- Native PyPilot Engine → Doctor and Fixes: produces diagnosis and fixes (evidence: `README.md`)
- Native PyPilot Engine → Python Version Resolution: resolves supported versions (evidence: `README.md`)
- Native PyPilot Engine → CUDA and Driver Matching: matches CUDA wheels (evidence: `README.md`)
- Native PyPilot Engine → Import Diagnostics: checks imports (evidence: `README.md`)
- Report Coordination → Workspace Language Clients: requests details from (evidence: `src/report.ts`)
- Report Coordination → Interactive Report Panel: shows report in (evidence: `src/report.ts`)
- Interactive Report Panel → VS Code: exports or copies (evidence: `src/webview/reportPanel.ts`)
- Python Developer → Command Handlers: runs commands (evidence: `README.md`)
- Python Developer → Workspace Tasks: runs tasks (evidence: `README.md`)
- Python Developer → Interactive Report Panel: views report (evidence: `README.md`)
