# microsoft/debugpy architecture

> Architecture diagram of the GitHub repository microsoft/debugpy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/debugpy
- Repository: https://github.com/microsoft/debugpy

## Overview

##### Main Components

a. Core Components:
- Debug Adapter (src/debugpy/adapter/)
- Launcher (src/debugpy/launcher/)
- Server (src/debugpy/server/)
- Common Utilities (src/debugpy/common/)

b. External Interfaces:
- DAP Client (e.g., VS Code)
- Python Debuggee (Target Application)
- Debug Adapter Protocol

##### Component Relationships

**Top Layer: Client Interface**
**Middle Layer: Debug Adapter Components**
**Bottom Layer: Target Python Application**

##### Specific Elements

a. Client Layer:
- Protocol connection lines showing JSON communication

b. Debug Adapter Layer:
- Adapter Component (handles DAP communication)
- Server Component (manages debugging sessions)
- Launcher Component (controls debuggee process)
- PyDevd Integration (vendored debugging engine)

c. Target Layer:
- Python Application
- Subprocess handling
- Remote debugging support

##### Flow Directions

- Client ↔ Debug Adapter (DAP protocol)
- Debug Adapter ↔ Server (internal communication)
- Server ↔ Python Application (debugging operations)

##### Important Features to Highlight

- Remote debugging capability
- Subprocess debugging
- Multiple client support
- Breakpoint handling
- Variable inspection
- Step debugging

##### Additional Details

Notes for:
- Port configuration (default 5678)
- Support for different Python versions
- Integration with PyDevd
- Cross-platform compatibility

##### Attach mode (debugpy connects to running process)

This architecture should reflect debugpy's ability to handle both local and remote debugging scenarios, while maintaining a clean separation of concerns between protocol handling and debugging implementation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        DAP["DAP Client (e.g., VS Code)"]:::client
    end

    subgraph "Debug Adapter Layer"
        Adapter["Debug Adapter"]:::core
        click Adapter "https://github.com/microsoft/debugpy/tree/main/src/debugpy/adapter/"
        AdapterInit["Adapter Init"]:::core
        click AdapterInit "https://github.com/microsoft/debugpy/blob/main/src/debugpy/adapter/__init__.py"
        ClientHandler["Client Handler"]:::core
        click ClientHandler "https://github.com/microsoft/debugpy/blob/main/src/debugpy/adapter/clients.py"
        SessionMgr["Session Manager"]:::core
        click SessionMgr "https://github.com/microsoft/debugpy/blob/main/src/debugpy/adapter/sessions.py"
    end

    subgraph "Server Layer"
        Server["Server Component"]:::core
        click Server "https://github.com/microsoft/debugpy/tree/main/src/debugpy/server/"
        ServerAPI["Server API"]:::core
        click ServerAPI "https://github.com/microsoft/debugpy/blob/main/src/debugpy/server/api.py"
        ServerCLI["CLI Interface"]:::core
        click ServerCLI "https://github.com/microsoft/debugpy/blob/main/src/debugpy/server/cli.py"
    end

    subgraph "Launcher Layer"
        Launcher["Launcher Component"]:::core
        click Launcher "https://github.com/microsoft/debugpy/tree/main/src/debugpy/launcher/"
        Debuggee["Debuggee Handler"]:::core
        click Debuggee "https://github.com/microsoft/debugpy/blob/main/src/debugpy/launcher/debuggee.py"
        Output["Output Handler"]:::core
        click Output "https://github.com/microsoft/debugpy/blob/main/src/debugpy/launcher/output.py"
    end

    subgraph "Common Utilities"
        Utils["Common Utils"]:::util
        click Utils "https://github.com/microsoft/debugpy/tree/main/src/debugpy/common/"
        JSON["JSON Handler"]:::util
        click JSON "https://github.com/microsoft/debugpy/blob/main/src/debugpy/common/json.py"
        Logging["Logging"]:::util
        click Logging "https://github.com/microsoft/debugpy/blob/main/src/debugpy/common/log.py"
        Messaging["Messaging"]:::util
        click Messaging "https://github.com/microsoft/debugpy/blob/main/src/debugpy/common/messaging.py"
        Sockets["Socket Utils"]:::util
        click Sockets "https://github.com/microsoft/debugpy/blob/main/src/debugpy/common/sockets.py"
    end

    subgraph "PyDevd Integration"
        PyDevd["PyDevd Core"]:::pydevd
        click PyDevd "https://github.com/microsoft/debugpy/blob/main/src/debugpy/_vendored/pydevd/pydevd.py"
        PyDevdAPI["PyDevd API"]:::pydevd
        click PyDevdAPI "https://github.com/microsoft/debugpy/blob/main/src/debugpy/_vendored/pydevd/_pydevd_bundle/pydevd_api.py"
        DAPSchema["DAP Schema"]:::pydevd
        click DAPSchema "https://github.com/microsoft/debugpy/blob/main/src/debugpy/_vendored/pydevd/_pydevd_bundle/_debug_adapter/pydevd_schema.py"
    end

    subgraph "Target Application"
        PythonApp["Python Application"]:::target
        PublicAPI["Public API"]:::api
        click PublicAPI "https://github.com/microsoft/debugpy/blob/main/src/debugpy/public_api.py"
    end

    %% Connections
    DAP <--> |"DAP Protocol (JSON)"| Adapter
    Adapter --> AdapterInit
    Adapter --> ClientHandler
    Adapter --> SessionMgr
    
    Adapter <--> |"Internal Communication"| Server
    Server --> ServerAPI
    Server --> ServerCLI
    
    Server <--> Launcher
    Launcher --> Debuggee
    Launcher --> Output
    
    Server --> Utils
    Utils --> JSON
    Utils --> Logging
    Utils --> Messaging
    Utils --> Sockets
    
    Server <--> PyDevd
    PyDevd --> PyDevdAPI
    PyDevd --> DAPSchema
    
    Launcher <--> PythonApp
    PythonApp --> PublicAPI

    %% Styles
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef client fill:#4CAF50,stroke:#2E7D32,color:white
    classDef util fill:#9E9E9E,stroke:#616161,color:white
    classDef pydevd fill:#FF9800,stroke:#F57C00,color:white
    classDef target fill:#E91E63,stroke:#C2185B,color:white
    classDef api fill:#673AB7,stroke:#512DA8,color:white

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Client Interface"]:::client
        L3["Utilities"]:::util
        L4["PyDevd Components"]:::pydevd
        L5["Target Application"]:::target
        L6["API Interface"]:::api
    end
```
