# aws/aws-toolkit-vscode architecture

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

- Interactive diagram: https://gitdiagram.com/aws/aws-toolkit-vscode
- Repository: https://github.com/aws/aws-toolkit-vscode

## Overview

##### Project type and purpose
- This is a monorepo hosting two VS Code extensions—“Amazon Q” and “AWS Toolkit”—plus shared libraries and plugins.
- It provides IDE integrations: inline code suggestions, chat‑based code generation, security scanning, AWS resource browsing, Lambda debugging, CloudFormation/SAM editing, etc.
- It is implemented in TypeScript and runs inside the VS Code Extension Host, with some code running in Webviews (browser contexts).

##### File structure
- Top‑level folders:
– packages/amazonq – Amazon Q extension
– packages/toolkit – AWS Toolkit extension
– packages/core   – shared utilities, common VS Code activation, AWS‑SDK clients, telemetry, LSP support, webview generators, sam/CFN support, chat DB
– plugins – custom ESLint rules
– src.gen – auto‑generated AWS streaming client SDKs
– .github, buildspec, scripts – CI/CD configuration and release pipelines
– docs, designs – architecture documentation and design proposals
- Tests are organized under each package, with unit, integration, E2E, and lint checks.
- Build tooling: webpack configs, tsconfig, copyFiles scripts, generateServiceClient scripts.

##### Read README for additional insights
- Amazon Q uses the generated streaming client (src.gen/@amzn/amazon-q-developer-streaming-client) to communicate with the Amazon Q AI backend.
- AWS Toolkit uses shared/core clients to communicate with IAM, EC2, S3, Lambda, CloudWatch, Step Functions, etc.
- Both extensions register VS Code commands, controllers, and Webview UIs.

##### Main components and interactions
A. VS Code IDE UI
– User input: keypresses, command palette, explorer clicks
– Hosts Webview panels (chat, code actions, security panel)
B. VS Code Extension Host (Node.js process)
– amazonq extension activation
– toolkit extension activation
– shared/core activation code, global services (telemetry, AWS client builder, credential manager)
– command registrations & handlers (commands.ts)
– controllers & providers layer (chat controllers, LSP controllers, code lenses, decorators)
C. Webview contexts (Browser)
– Chat UI, code suggestion UI, security/fix UI
– Message dispatcher to Extension Host via postMessage
D. Language Server Protocol (LSP) support
– shared LSP installer & resolver
– language server client & server modules (for inline completions, CFN templates)
E. AWS‐SDK Client Layer
– shared/clients/* clients for each AWS service
– credential providers (IAM, SSO, AWS Builder ID)
F. Generative AI Services
– Amazon Q API (via amazon‑q‑developer‑streaming‑client)
– CodeWhisperer streaming client
G. Local Tooling
– SAM CLI integration for Lambda debugging (shared/sam/cli)
H. CI/CD & Release
– GitHub Actions & AWS CodeBuild (buildspec files)
– Marketplace publishing steps in buildspec/release

##### Architectural patterns and principles
- Monorepo modularity: clear package boundaries (amazonq, toolkit, core).
- Layered architecture: UI (Webview + VS Code commands) → controllers → service clients → external APIs.
- MVC‑like separation in chat features: models (session, constants), controllers (messenger, session), views (UI connectors, message listeners).
- Shared services via dependency injection in core: telemetry, AWS client builder, credential manager.
- Code generation: src.gen for AWS streaming clients; build scripts auto‑generate service clients and configuration attributes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and IDE
    User["User"]:::external
    VSCodeUI["VS Code IDE UI"]:::external
    User -->|"interacts"| VSCodeUI

    %% Extension Host
    subgraph "VS Code Extension Host (Node.js)" 
        direction TB
        AQ_Activation["amazonq Activation"]:::host
        TL_Activation["toolkit Activation"]:::host
        Core_Activation["core Activation"]:::host

        AQ_Commands["amazonq commands.ts"]:::host
        Core_Commands["core commands.ts"]:::host

        subgraph "Controllers & Providers"
            direction TB
            AQ_ChatController["amazonqScan Chat Controller"]:::host
            AQ_InlineController["Inline Chat Controller"]:::host
            LSP_ClientServer["amazonq LSP Client & Installer"]:::host
            AWS_Clients["AWS Service Clients"]:::shared
            AWS_Builder["AWS Client Builders"]:::shared
            Credentials["Credential Manager & Providers"]:::shared
            Telemetry["Telemetry Service"]:::shared
            SAM_CLI["SAM CLI Integration"]:::shared
            LSP_InstallerResolver["LSP Installer & Resolver"]:::shared
            AWExplorer["AWS Resource Explorer"]:::shared
        end

        AQ_Activation -->|initializes| AQ_Commands
        TL_Activation -->|initializes| Core_Commands
        Core_Activation -->|initializes| Core_Commands
        AQ_Commands -->|registers| AQ_ChatController
        AQ_Commands -->|registers| AQ_InlineController
        TL_Activation -->|uses| AWS_Clients
        Core_Activation -->|provides| AWS_Builder
        Core_Activation -->|provides| Credentials
        Core_Activation -->|provides| Telemetry
        Core_Activation -->|provides| SAM_CLI
        Core_Activation -->|provides| LSP_InstallerResolver
        Core_Activation -->|provides| AWExplorer
        AQ_ChatController -->|uses| AWS_Clients
        AQ_InlineController -->|uses| AWS_Clients
        LSP_ClientServer -->|uses| LSP_InstallerResolver
    end

    %% Webviews
    subgraph "Webview Processes (Browser)"
        direction TB
        ChatUI["Chat UI Webview"]:::external
        CodeSuggestUI["Code Suggestion UI"]:::external
        SecurityUI["Security Panel UI"]:::external
        ChatUI -->|postMessage/onDidReceiveMessage| AQ_ChatController
        CodeSuggestUI -->|postMessage| AQ_InlineController
        SecurityUI -->|postMessage| AQ_ChatController
    end

    %% External Services
    subgraph "External APIs" 
        direction TB
        AmazonQ_API["Amazon Q Streaming API"]:::externalService
        CodeWhisperer_API["CodeWhisperer Streaming API"]:::externalService
        AWS_Service["AWS Services (IAM, S3, Lambda, etc.)"]:::externalService
        AQ_ChatController -->|stream| AmazonQ_API
        AQ_InlineController -->|stream| CodeWhisperer_API
        AWS_Clients -->|calls| AWS_Service
    end

    %% CI/CD & Release
    subgraph "CI/CD & Release Pipeline"
        direction TB
        GH_Actions["GitHub Actions"]:::ci
        CodeBuild["AWS CodeBuild"]:::ci
        ReleaseScripts["Release & Version Bump Scripts"]:::ci
        GH_Actions -->|triggers| CodeBuild
        CodeBuild -->|builds & publishes| ReleaseScripts
    end

    %% Build & Gen
    srcGen["Generated Streaming Clients"]:::shared
    srcGen -->|used by| AQ_ChatController
    srcGen -->|used by| AQ_InlineController
    Core_Activation -->|loads| srcGen

    %% Connections IDE to Host
    VSCodeUI -->|commands, events| AQ_Activation
    VSCodeUI -->|commands, events| TL_Activation
    VSCodeUI -->|commands, events| Core_Activation

    %% Click Events
    click AQ_Activation "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/amazonq/src/extensionNode.ts"
    click TL_Activation "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/toolkit/src/extensionNode.ts"
    click Core_Activation "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/extensionNode.ts"
    click ChatUI "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/amazonq/src/extensionWeb.ts"
    click CodeSuggestUI "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/toolkit/src/extensionWeb.ts"
    click WebviewGenerator "https://github.com/aws/aws-toolkit-vscode/tree/master/packages/core/src/shared/webview"
    click webViewContent "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/amazonq/webview/generators/webViewContent.ts"
    click AQ_Commands "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/amazonq/src/commands.ts"
    click Core_Commands "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/commands.ts"
    click AQ_ChatController "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/amazonq/src/app/amazonqScan/chat/controller/controller.ts"
    click AQ_InlineController "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/amazonq/src/inlineChat/controller/inlineChatController.ts"
    click LSP_InstallerResolver "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/shared/lsp/baseLspInstaller.ts"
    click LSP_InstallerResolver "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/shared/lsp/lspResolver.ts"
    click LSP_ClientServer "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/amazonq/src/lsp/client.ts"
    click LSP_ClientServer "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/amazonq/src/lsp/lspInstaller.ts"
    click AWS_Builder "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/shared/awsClientBuilder.ts"
    click AWS_Builder "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/shared/awsClientBuilderV3.ts"
    click AWS_Clients "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/shared/clients/iam.ts"
    click AWS_Clients "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/shared/clients/lambdaClient.ts"
    click AWS_Clients "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/shared/clients/s3.ts"
    click srcGen "https://github.com/aws/aws-toolkit-vscode/blob/master/src.gen/@amzn/amazon-q-developer-streaming-client/src/QDeveloperStreamingClient.ts"
    click srcGen "https://github.com/aws/aws-toolkit-vscode/blob/master/src.gen/@amzn/codewhisperer-streaming/src/CodeWhispererStreamingClient.ts"
    click SAM_CLI "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/shared/sam/cli/samCliInvoker.ts"
    click GH_Actions "https://github.com/aws/aws-toolkit-vscode/blob/master/.github/workflows/node.js.yml"
    click GH_Actions "https://github.com/aws/aws-toolkit-vscode/blob/master/.github/workflows/release.yml"
    click CodeBuild "https://github.com/aws/aws-toolkit-vscode/blob/master/buildspec/release/10changeversion.yml"
    click CodeBuild "https://github.com/aws/aws-toolkit-vscode/blob/master/buildspec/release/20buildrelease.yml"
    click ReleaseScripts "https://github.com/aws/aws-toolkit-vscode/blob/master/scripts/createRelease.ts"
    click ReleaseScripts "https://github.com/aws/aws-toolkit-vscode/blob/master/scripts/newChange.ts"
    click AWExplorer "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/awsexplorer/awsExplorer.ts"
    click AWExplorer "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/awsexplorer/childNodeLoader.ts"
    click Telemetry "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/shared/telemetry/telemetryService.ts"
    click Telemetry "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/shared/telemetry/telemetry.ts"
    click Credentials "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/auth/providers/credentialsProviderManager.ts"
    click Credentials "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/auth/providers/ssoCredentialsProvider.ts"
    click SAM_CLI "https://github.com/aws/aws-toolkit-vscode/blob/master/packages/core/src/shared/sam/debugger/awsSamDebugger.ts"
    click ReleaseScripts "https://github.com/aws/aws-toolkit-vscode/blob/master/buildspec/release/60publish.yml"
    click ReleaseScripts "https://github.com/aws/aws-toolkit-vscode/blob/master/buildspec/release/70checkmarketplace.yml"
    click ESLintPlugin "https://github.com/aws/aws-toolkit-vscode/blob/master/plugins/eslint-plugin-aws-toolkits/lib/rules/no-index-import.ts"

    %% Styles
    classDef host fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef shared fill:#E6F4EA,stroke:#22863A,color:#22863A;
    classDef external fill:#F0F0F0,stroke:#666666,color:#333333;
    classDef externalService fill:#FFEDD5,stroke:#D9480F,color:#D9480F;
    classDef ci fill:#EDEFF2,stroke:#6A737D,color:#6A737D;
    classDef ESLintPlugin fill:#F5F5F5,stroke:#CCCCCC,color:#555555;
    class User,VSCodeUI,ChatUI,CodeSuggestUI,SecurityUI external
    class ESLintPlugin ci
```
