# aws/amazon-q-developer-cli architecture

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

- Interactive diagram: https://gitdiagram.com/aws/amazon-q-developer-cli
- Repository: https://github.com/aws/amazon-q-developer-cli

## Overview

##### Project Type and Purpose
- This is an open-source, multi-crate Rust monorepo that produces the “Amazon Q” command-line tool. Its primary purpose is to deliver a terminal-based IDE-style autocomplete and chat experience by:
- Invoking AWS Q-Developer service APIs (via generated service clients under `crates/amzn-*`).
- Managing natural-language chat flows (`chat_cli` binary in `crates/cli`).
- Persisting conversation history and context locally (SQLite).
- Streaming events for long-polling and agentic execution.
- Exposing extension points for VSCode/JetBrains via a mini MCP (JSON-RPC over stdio or WebSocket).

##### Top-Level Components
- Front-end binaries
- `chat_cli` (in `crates/cli/src/main.rs`): orchestrates commands (`q chat`, `q feed`, etc.).
- Core Libraries
- `api_client` (under `crates/cli/src/api_client`): request builder, credential management, interceptors.
- AWS Q service SDK crates (`crates/amzn-codewhisperer-client`, `-streaming-client`, `-consolas-client`, `-qdeveloper-streaming-client`, `-toolkit-telemetry-client`).
- MCP transport (`crates/cli/src/mcp_client`): JSON-RPC wire protocol for IDE integrations.
- Local database module (`crates/cli/src/database`): SQLite migrations, state/history tables.
- External Services
- AWS Q-Developer APIs (CodeWhisperer, Streaming Assistant, Consolas customizations, Q-Developer commands).
- Telemetry endpoints.
- Extensions & IDE Integrations
- VSCode / JetBrains extensions invoking the CLI via MCP.
- Support Artifacts
- Build scripts (`scripts/`), documentation site (`docs/`), pre-commit hooks.

##### Interactions & Data Flow
- User types a `q` command in the terminal.
→ CLI parser dispatches to a subcommand (`chat_cli`, `feed`, `issue`, etc.).
→ For `chat`: Chat module collects environment context (cwd, files), loads history from SQLite, renders prompt.
→ API requests are built via `api_client`, sent to AWS Q APIs through the generated AWS service crates.
→ Streaming responses (events) are handled by the streaming client crates, displayed in real time.
→ Conversations and state updates are written back to the local SQLite DB.
→ If user installs VSCode extension, the CLI runs in MCP server mode, exchanging JSON-RPC over stdio/WebSocket.

##### Architectural Patterns & Design Principles
- Modular crate-per-service approach: each AWS service has its own generated client crate.
- Thin orchestration layer in the `cli` crate, separating command parsing, API calling, streaming consumption, and persistence.
- Clear separation between:
- Presentation (terminal UI / MCP protocol)
- Domain logic (chat orchestration)
- Infrastructure (AWS HTTP client, telemetry, database)
- Event-driven streaming: uses `event_receiver.rs` and `event_stream_serde.rs` in streaming crates.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        TerminalUI["Terminal UI\n(chat_cli)"]:::rustCrate
        IDEExt["IDE Extensions\n(VSCode/JetBrains)"]:::ide
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        Orchestration["CLI Orchestration\n(command dispatch & subcommands)"]:::rustCrate
        Subcommands["Subcommand Implementations\n(chat, feed, issue, etc.)"]:::rustCrate
        APIClient["API Client Layer\n(request builder, cred, interceptors)"]:::rustCrate
        AWSCommon["Shared AWS Common Helpers"]:::rustCrate
        Auth["Authentication Helpers"]:::rustCrate
        TelemetryInt["Telemetry Integration"]:::rustCrate
        Platform["Platform Abstractions"]:::rustCrate
        Util["Utility Modules"]:::rustCrate
        MCPClient["MCP Transport/Protocol\n(JSON-RPC over stdio/WebSocket)"]:::ide
    end

    %% AWS SDK Clients
    subgraph "AWS SDK Clients"
        direction TB
        CWClient["CodeWhisperer Client"]:::rustCrate
        CWStream["CodeWhisperer Streaming Client"]:::rustCrate
        Consolas["Consolas Customizations Client"]:::rustCrate
        QDevStream["Q-Developer Streaming Client"]:::rustCrate
        TelemetryClient["Toolkit Telemetry Client"]:::rustCrate
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        LocalDB["Local SQLite Database"]:::db
    end

    %% External Services
    subgraph "External AWS Q-Developer Services"
        direction TB
        AWSQDev["AWS Q-Developer APIs"]:::external
        TelemetryEP["Telemetry Endpoints"]:::external
    end

    %% Support Artifacts
    subgraph "Support Artifacts"
        direction TB
        BuildScripts["Build Scripts"]:::support
        DocsSite["Documentation Site & Assets"]:::support
        CIWorkflows["CI & Workflows"]:::support
    end

    %% Connections
    TerminalUI -->|invokes| Orchestration
    IDEExt -->|JSON-RPC| MCPClient
    MCPClient -->|dispatch commands| Orchestration

    Orchestration -->|calls| Subcommands
    Orchestration -->|uses| APIClient
    Orchestration -->|writes| LocalDB
    Subcommands -->|uses| APIClient

    APIClient -->|depends on| AWSCommon
    APIClient -->|auth via| Auth
    APIClient -->|emit telemetry| TelemetryInt
    APIClient -->|platform ops| Platform
    APIClient -->|utils| Util

    APIClient -->|HTTP/REST| CWClient
    APIClient -->|HTTP/REST| Consolas
    APIClient -->|HTTP/REST| QDevStream
    APIClient -->|HTTP/REST| TelemetryClient

    CWClient -->|REST| AWSQDev
    Consolas -->|REST| AWSQDev
    QDevStream -->|stream| AWSQDev
    TelemetryClient -->|REST| TelemetryEP

    CWStream -->|stream events| Orchestration
    QDevStream -->|stream events| Orchestration

    BuildScripts --> CIWorkflows
    DocsSite --> CIWorkflows

    %% Click Events
    click TerminalUI "https://github.com/aws/amazon-q-developer-cli/blob/main/crates/cli/src/main.rs"
    click Orchestration "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/cli/src/cli/"
    click APIClient "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/cli/src/api_client/"
    click MCPClient "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/cli/src/mcp_client/"
    click LocalDB "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/cli/src/database/"
    click CWClient "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/amzn-codewhisperer-client/"
    click CWStream "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/amzn-codewhisperer-streaming-client/"
    click Consolas "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/amzn-consolas-client/"
    click QDevStream "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/amzn-qdeveloper-streaming-client/"
    click TelemetryClient "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/amzn-toolkit-telemetry-client/"
    click Subcommands "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/cli/src/cli/chat/"
    click Subcommands "https://github.com/aws/amazon-q-developer-cli/blob/main/crates/cli/src/cli/feed.rs"
    click Subcommands "https://github.com/aws/amazon-q-developer-cli/blob/main/crates/cli/src/cli/issue.rs"
    click AWSCommon "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/cli/src/aws_common/"
    click Auth "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/cli/src/auth/"
    click TelemetryInt "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/cli/src/telemetry/"
    click Platform "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/cli/src/platform/"
    click Util "https://github.com/aws/amazon-q-developer-cli/tree/main/crates/cli/src/util/"
    click BuildScripts "https://github.com/aws/amazon-q-developer-cli/tree/main/scripts/"
    click DocsSite "https://github.com/aws/amazon-q-developer-cli/tree/main/docs/"
    click CIWorkflows "https://github.com/aws/amazon-q-developer-cli/tree/main/.github/workflows/"

    %% Styles
    classDef rustCrate fill:#ADD8E6,stroke:#000,color:#000
    classDef external fill:#90EE90,stroke:#000,color:#000
    classDef db fill:#FFA500,stroke:#000,color:#000
    classDef ide fill:#DDA0DD,stroke:#000,color:#000
    classDef support fill:#CCCCCC,stroke:#000,color:#000
```
