# microsoft/vscode-cdp architecture

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

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

## Overview

##### Main Components
- Client Component: Represented by files like src/client.ts and its corresponding tests. This is where the consumer’s connection is established and the CDP API is consumed.
- Server Component: Shown by src/server.ts and related tests. This part is for implementing a CDP server and exposing APIs.
- Connection and Session Management: Files such as src/connection.ts, src/cdp-session.ts, and src/cdp-protocol.ts define how sessions and connections are managed between client and server.
- Transport Layer: Located in the src/transport folder with different transport implementations (e.g., websocket.ts for real-time, network-based communication and loopback.ts for internal simulation). This encapsulates the details of the underlying communication mechanism.
- Serialization: The src/serializer directory (with files like json.ts) handles transforming requests and responses between JSON (or other formats) and strong TypeScript types.
- Build/Utility Tools: The src/build folder contains scripts and utilities (like download-types.ts, pdl-types.ts, pdlToTypeScript.ts, and pdl2json scripts) aiming to format, generate, and test protocol definitions. These are tools that support the main functionality by automating type generation or protocol conversion.
- Error Handling and Cancellation: Files such as src/errors.ts and src/cancellation.ts ensure that error cases and asynchronous cancellations are properly handled.

##### Relationships and Data Flow
- The Client component uses the Connection layer to establish sessions. The Connection layer acts as a mediator between the Client and the Transport layer.
- The Transport layer (e.g., WebSocketTransport) is responsible for handling the raw communication with external services (like a browser’s CDP server or another external process).
- Data (commands and events) flows from the Client through the Connection, is serialized (via the Serializer), transmitted over the Transport, and handled by the Server (or vice versa for events and responses).
- The Build utilities (in the build directory) interact indirectly: they are used during development and build-time to generate the type-safe API definitions that the client and server consume.
- Custom domain extensions are supported by both client and server, allowing developers to mix in additional API domains beyond the default ones.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The division into client, server, transport, connection, and serialization components clearly separates user-facing API logic, connection management, and data transformation/communication layers.
- Extensibility: The architecture accommodates custom domains and extension of protocol definitions, allowing for flexible integration.
- Strong Typing: Use of TypeScript generics and interface definitions provides compile-time safety for interactions with the Chrome DevTools Protocol.
- Testability: Dedicated test files for most components (client, connection, server, build utilities) indicate a focus on maintainability and reliability.

##### Relevant Technologies and Frameworks
- TypeScript is at the core, ensuring strong typing.
- Node.js and its ecosystem (e.g., usage of WebSocket servers) are implied by files like pdl2json.py and the configuration of tools.
- Testing frameworks (evident from jest.config.js and test files) underline that automated testing is part of the development process.
- WebSocket protocols for client-server communication via the transport components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Components
    subgraph "Runtime Components"
        Client["Client"]:::runtime
        subgraph "Connection Layer"
            ConnectionCore["Connection (connection.ts)"]:::runtime
            CdpSession["CDP Session (cdp-session.ts)"]:::runtime
            CdpProtocol["CDP Protocol (cdp-protocol.ts)"]:::runtime
        end
        Serializer["Serializer (src/serializer/index.ts)"]:::runtime
        JSONSer["JSON Serializer (src/serializer/json.ts)"]:::runtime
        subgraph "Transport Layer"
            WebSocket["WebSocket (websocket.ts)"]:::runtime
            Loopback["Loopback (loopback.ts)"]:::runtime
            TransportIndex["Transport Index (index.ts)"]:::runtime
        end
        Server["Server (src/server.ts)"]:::runtime
        CustomDomains["Custom Domains"]:::extension
        subgraph "Error Management"
            ErrorHandling["Error Handling (errors.ts)"]:::error
            Cancellation["Cancellation (cancellation.ts)"]:::error
        end
    end

    %% Build/Utility Tools
    subgraph "Build/Utility Tools"
        DownloadTypes["download-types.ts"]:::build
        PdlTypes["pdl-types.ts"]:::build
        Pdl2jsonPy["pdl2json.py"]:::build
        Pdl2jsonTs["pdl2json.ts"]:::build
        PdlToTypeScript["pdlToTypeScript.ts"]:::build
        Format["format.ts"]:::build
    end

    %% Test Suites
    subgraph "Test Suites"
        ClientTest["Client Tests"]:::test
        ServerTest["Server Tests"]:::test
        ConnectionTest["Connection Tests"]:::test
    end

    %% Data Flow - Runtime Communication
    Client -->|"connects"| ConnectionCore
    ConnectionCore -->|"createsSession"| CdpSession
    CdpSession -->|"managesProtocol"| CdpProtocol
    CdpProtocol -->|"serializes"| Serializer
    Serializer -->|"formatsToJSON"| JSONSer
    JSONSer -->|"sendsData"| WebSocket
    JSONSer -->|"sendsData"| Loopback
    JSONSer -->|"sendsData"| TransportIndex
    WebSocket -->|"deliversCommand"| Server
    Loopback -->|"deliversCommand"| Server
    TransportIndex -->|"deliversCommand"| Server
    Server -->|"sendsEvent"| WebSocket
    Server -->|"sendsEvent"| Loopback
    Server -->|"sendsEvent"| TransportIndex
    WebSocket -->|"returnsEvent"| JSONSer
    Loopback -->|"returnsEvent"| JSONSer
    TransportIndex -->|"returnsEvent"| JSONSer
    JSONSer -->|"deserializes"| CdpProtocol
    CdpProtocol -->|"updatesSession"| CdpSession
    CdpSession -->|"reportsStatus"| ConnectionCore
    ConnectionCore -->|"notifies"| Client

    %% Custom Domains Integration
    CustomDomains -->|"extends"| Client
    CustomDomains -->|"extends"| Server

    %% Error and Cancellation links (dotted lines)
    ErrorHandling -.-> ConnectionCore
    Cancellation -.-> ConnectionCore
    ErrorHandling -.-> Server
    Cancellation -.-> Server

    %% Build Tools interaction (dashed connections)
    DownloadTypes ---|"generatesTypes"| Serializer
    PdlTypes ---|"generatesTypes"| Serializer
    Pdl2jsonPy ---|"generatesTypes"| Serializer
    Pdl2jsonTs ---|"generatesTypes"| Serializer
    PdlToTypeScript ---|"generatesTypes"| Serializer
    Format ---|"formats"| Serializer
    DownloadTypes ---|"defines"| Client
    PdlTypes ---|"defines"| Server

    %% Test Suites associations (dotted lines)
    ClientTest -.-> Client
    ServerTest -.-> Server
    ConnectionTest -.-> ConnectionCore

    %% Click Events
    click Client "https://github.com/microsoft/vscode-cdp/blob/main/src/client.ts"
    click ClientTest "https://github.com/microsoft/vscode-cdp/blob/main/src/client.test.ts"
    click Server "https://github.com/microsoft/vscode-cdp/blob/main/src/server.ts"
    click ServerTest "https://github.com/microsoft/vscode-cdp/blob/main/src/server.test.ts"
    click ConnectionCore "https://github.com/microsoft/vscode-cdp/blob/main/src/connection.ts"
    click CdpSession "https://github.com/microsoft/vscode-cdp/blob/main/src/cdp-session.ts"
    click CdpProtocol "https://github.com/microsoft/vscode-cdp/blob/main/src/cdp-protocol.ts"
    click ConnectionTest "https://github.com/microsoft/vscode-cdp/blob/main/src/connection.test.ts"
    click WebSocket "https://github.com/microsoft/vscode-cdp/blob/main/src/transport/websocket.ts"
    click Loopback "https://github.com/microsoft/vscode-cdp/blob/main/src/transport/loopback.ts"
    click TransportIndex "https://github.com/microsoft/vscode-cdp/blob/main/src/transport/index.ts"
    click Serializer "https://github.com/microsoft/vscode-cdp/blob/main/src/serializer/index.ts"
    click JSONSer "https://github.com/microsoft/vscode-cdp/blob/main/src/serializer/json.ts"
    click DownloadTypes "https://github.com/microsoft/vscode-cdp/blob/main/src/build/download-types.ts"
    click PdlTypes "https://github.com/microsoft/vscode-cdp/blob/main/src/build/pdl-types.ts"
    click Pdl2jsonPy "https://github.com/microsoft/vscode-cdp/blob/main/src/build/pdl2json.py"
    click Pdl2jsonTs "https://github.com/microsoft/vscode-cdp/blob/main/src/build/pdl2json.ts"
    click PdlToTypeScript "https://github.com/microsoft/vscode-cdp/blob/main/src/build/pdlToTypeScript.ts"
    click Format "https://github.com/microsoft/vscode-cdp/blob/main/src/build/format.ts"
    click ErrorHandling "https://github.com/microsoft/vscode-cdp/blob/main/src/errors.ts"
    click Cancellation "https://github.com/microsoft/vscode-cdp/blob/main/src/cancellation.ts"

    %% Styles
    classDef runtime fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef build fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef test fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef error fill:#fdfd96,stroke:#c1c10d,stroke-width:2px;
    classDef extension fill:#e2e3e5,stroke:#818182,stroke-width:2px;
```
