# djsaunders1997/uv-wingman architecture

> Architecture diagram of the GitHub repository djsaunders1997/uv-wingman, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/djsaunders1997/uv-wingman
- Repository: https://github.com/djsaunders1997/uv-wingman

## Overview

UV Wingman is a VS Code extension for managing uv projects. Users invoke commands or status-bar actions to initialize projects, create and activate environments, sync or edit dependencies, and run scripts; these actions build shell-specific commands and send them to the integrated terminal. The extension also manages Python interpreter selection and presents dependency links, version hints, and an interactive graph. The graph reflects sampled call sites and README capabilities; unsampled command-registration details and some UI wiring are not inferred beyond documented behavior.

Main entry points: [`src/extension.js`](https://github.com/djsaunders1997/uv-wingman/blob/main/src/extension.js) (Extension activation), [`src/commands.js`](https://github.com/djsaunders1997/uv-wingman/blob/main/src/commands.js) (Project commands), [`src/dependencyGraphPanel.js`](https://github.com/djsaunders1997/uv-wingman/blob/main/src/dependencyGraphPanel.js) (Dependency graph panel), [`src/statusBarItems.js`](https://github.com/djsaunders1997/uv-wingman/blob/main/src/statusBarItems.js) (Status bar)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_activation["Extension UI"]
  node_extension["Extension activation<br/>[extension.js]"]
  node_status["Status bar<br/>[statusBarItems.js]"]
end

subgraph group_management["Project management"]
  node_commands["Project commands<br/>[commands.js]"]
  node_terminalcmds["Shell commands"]
  node_interpreter["Interpreter management<br/>[interpreter.js]"]
end

subgraph group_insights["Dependency insights"]
  node_links["PyPI document links<br/>[documentLinks.js]"]
  node_codelens["Version hints<br/>[codeLens.js]"]
  node_graphpanel["Dependency graph panel"]
  node_graphbuild["Graph construction<br/>[dependencyGraph.js]"]
  node_webview["Graph visualization"]
end

subgraph group_support["Shared services"]
  node_config["Extension settings<br/>[config.js]"]
  node_utils["Workspace and terminal utilities<br/>[utils.js]"]
  node_toml["TOML dependency parsing<br/>[tomlParser.js]"]
end

node_developer(("VS Code user"))
node_terminal["Integrated terminal"]
node_pypi["PyPI"]
node_uv["uv CLI"]
node_python["Python interpreter setting"]

node_developer -->|"uses extension"| node_extension
node_extension -->|"registers commands"| node_commands
node_extension -->|"initializes status"| node_status
node_extension -->|"registers links"| node_links
node_extension -->|"registers hints"| node_codelens
node_commands -->|"builds commands"| node_terminalcmds
node_commands -->|"sends terminal text"| node_utils
node_commands -->|"sets interpreter"| node_interpreter
node_commands -->|"updates display"| node_status
node_terminalcmds -->|"reads env name"| node_config
node_terminalcmds -.->|"provides shell commands"| node_terminal
node_utils -->|"sends command"| node_terminal
node_interpreter -->|"reads env name"| node_config
node_interpreter -->|"updates setting"| node_python
node_status -->|"reads settings"| node_config
node_status -->|"checks env version"| node_python
node_links -->|"finds package positions"| node_toml
node_links -->|"links packages"| node_pypi
node_codelens -->|"finds dependency positions"| node_toml
node_codelens -->|"fetches package data"| node_pypi
node_extension -->|"opens graph"| node_graphpanel
node_graphpanel -->|"builds graph data"| node_graphbuild
node_graphpanel -->|"renders graph"| node_webview
node_graphbuild -->|"parses project dependencies"| node_toml
node_graphpanel -->|"gets workspace"| node_utils
node_developer -->|"clicks actions"| node_status
node_developer -->|"requests visualization"| node_graphpanel

click node_extension "https://github.com/djsaunders1997/uv-wingman/blob/main/src/extension.js"
click node_commands "https://github.com/djsaunders1997/uv-wingman/blob/main/src/commands.js"
click node_status "https://github.com/djsaunders1997/uv-wingman/blob/main/src/statusBarItems.js"
click node_terminalcmds "https://github.com/djsaunders1997/uv-wingman/blob/main/src/terminalCommands.js"
click node_interpreter "https://github.com/djsaunders1997/uv-wingman/blob/main/src/interpreter.js"
click node_config "https://github.com/djsaunders1997/uv-wingman/blob/main/src/config.js"
click node_utils "https://github.com/djsaunders1997/uv-wingman/blob/main/src/utils.js"
click node_toml "https://github.com/djsaunders1997/uv-wingman/blob/main/src/tomlParser.js"
click node_links "https://github.com/djsaunders1997/uv-wingman/blob/main/src/documentLinks.js"
click node_codelens "https://github.com/djsaunders1997/uv-wingman/blob/main/src/codeLens.js"
click node_graphpanel "https://github.com/djsaunders1997/uv-wingman/blob/main/src/dependencyGraphPanel.js"
click node_graphbuild "https://github.com/djsaunders1997/uv-wingman/blob/main/src/dependencyGraph.js"
click node_webview "https://github.com/djsaunders1997/uv-wingman/blob/main/media/dependencyGraph.html"

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_status,node_developer toneBlue
class node_commands,node_terminalcmds,node_interpreter toneAmber
class node_links,node_codelens,node_graphpanel,node_graphbuild,node_webview toneMint
class node_config,node_utils,node_toml toneRose
class node_terminal,node_pypi,node_uv,node_python toneIndigo
```

## Components

### Extension UI

- [Extension activation](https://github.com/djsaunders1997/uv-wingman/blob/main/src/extension.js): `src/extension.js`
- [Status bar](https://github.com/djsaunders1997/uv-wingman/blob/main/src/statusBarItems.js): `src/statusBarItems.js`

### Project management

- [Project commands](https://github.com/djsaunders1997/uv-wingman/blob/main/src/commands.js): `src/commands.js`
- [Shell commands](https://github.com/djsaunders1997/uv-wingman/blob/main/src/terminalCommands.js): `src/terminalCommands.js`
- [Interpreter management](https://github.com/djsaunders1997/uv-wingman/blob/main/src/interpreter.js): `src/interpreter.js`

### Dependency insights

- [PyPI document links](https://github.com/djsaunders1997/uv-wingman/blob/main/src/documentLinks.js): `src/documentLinks.js`
- [Version hints](https://github.com/djsaunders1997/uv-wingman/blob/main/src/codeLens.js): `src/codeLens.js`
- [Dependency graph panel](https://github.com/djsaunders1997/uv-wingman/blob/main/src/dependencyGraphPanel.js): `src/dependencyGraphPanel.js`
- [Graph construction](https://github.com/djsaunders1997/uv-wingman/blob/main/src/dependencyGraph.js): `src/dependencyGraph.js`
- [Graph visualization](https://github.com/djsaunders1997/uv-wingman/blob/main/media/dependencyGraph.html): `media/dependencyGraph.html`

### Shared services

- [Extension settings](https://github.com/djsaunders1997/uv-wingman/blob/main/src/config.js): `src/config.js`
- [Workspace and terminal utilities](https://github.com/djsaunders1997/uv-wingman/blob/main/src/utils.js): `src/utils.js`
- [TOML dependency parsing](https://github.com/djsaunders1997/uv-wingman/blob/main/src/tomlParser.js): `src/tomlParser.js`

### Other components

- **VS Code user**
- **Integrated terminal**
- **PyPI**
- **uv CLI**
- **Python interpreter setting**

## Connections

- VS Code user → Extension activation: uses extension (evidence: `README.md`)
- Extension activation → Project commands: registers commands (evidence: `src/extension.js`)
- Extension activation → Status bar: initializes status (evidence: `src/extension.js`)
- Extension activation → PyPI document links: registers links (evidence: `src/extension.js`)
- Extension activation → Version hints: registers hints (evidence: `src/extension.js`)
- Project commands → Shell commands: builds commands (evidence: `src/commands.js`)
- Project commands → Workspace and terminal utilities: sends terminal text (evidence: `src/commands.js`)
- Project commands → Interpreter management: sets interpreter (evidence: `src/commands.js`)
- Project commands → Status bar: updates display (evidence: `src/commands.js`)
- Shell commands → Extension settings: reads env name (evidence: `src/terminalCommands.js`)
- Shell commands → Integrated terminal: provides shell commands
- Workspace and terminal utilities → Integrated terminal: sends command (evidence: `src/utils.js`)
- Interpreter management → Extension settings: reads env name (evidence: `src/interpreter.js`)
- Interpreter management → Python interpreter setting: updates setting (evidence: `src/interpreter.js`)
- Status bar → Extension settings: reads settings (evidence: `src/statusBarItems.js`)
- Status bar → Python interpreter setting: checks env version (evidence: `src/statusBarItems.js`)
- PyPI document links → TOML dependency parsing: finds package positions (evidence: `src/documentLinks.js`)
- PyPI document links → PyPI: links packages (evidence: `README.md`)
- Version hints → TOML dependency parsing: finds dependency positions (evidence: `src/codeLens.js`)
- Version hints → PyPI: fetches package data (evidence: `src/codeLens.js`)
- Extension activation → Dependency graph panel: opens graph (evidence: `src/extension.js`)
- Dependency graph panel → Graph construction: builds graph data (evidence: `src/dependencyGraphPanel.js`)
- Dependency graph panel → Graph visualization: renders graph (evidence: `src/dependencyGraphPanel.js`)
- Graph construction → TOML dependency parsing: parses project dependencies (evidence: `src/dependencyGraph.js`)
- Dependency graph panel → Workspace and terminal utilities: gets workspace (evidence: `src/dependencyGraphPanel.js`)
- VS Code user → Status bar: clicks actions (evidence: `README.md`)
- VS Code user → Dependency graph panel: requests visualization (evidence: `README.md`)
