# google/adk-web architecture

> Architecture diagram of the GitHub repository google/adk-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google/adk-web
- Repository: https://github.com/google/adk-web

## Overview

##### Project type and purpose
- This is a full-stack developer UI for the Google Agent Development Kit (ADK), implemented entirely as an Angular single-page application (SPA).
- Its purpose is to provide an interactive, visual interface for building, testing, and debugging AI agents powered by the ADK backend (a separate Python/Java API server).

##### File structure
- Top-level files and scripts:
- angular.json, tsconfig*.json, package.json / package-lock.json, karma.conf.js, karma scripts – Angular CLI configuration and build/test pipelines.
- clean-backend.js and set-backend.js – scripts to configure the API base-URL for local development.
- .github/workflows/angular-tests.yml – CI pipeline for running Angular tests.
- Public assets (`public/`, `src/assets/`):
- runtime-config.json – runtime config for API endpoints, feature flags, etc.
- audio-processor.js – custom audio processing in the browser.
- Source code (`src/`):
- `src/app/components/…` – a large set of Angular UI components grouped by feature tab (artifact-tab, eval-tab, chat-panel, trace-tab, etc.).
- `src/app/core/models/…` – TypeScript interfaces/models representing AgentRunRequest, Session, Trace, Eval, etc.
- `src/app/core/services/…` – Angular services that encapsulate HTTP and WebSocket calls to the backend; includes feature-flag, agent, eval, event, session, trace, artifact, audio playback/recording, download, local-file, stream-chat, video, UI state, etc.
- `src/app/directives/…` – custom Angular directives for resizing panels.
- `src/app/testing/…` – testing utilities and mocks for all core services.
- `src/env/` and `src/utils/` – environment constants and URL/ runtime-config helpers.

##### README for additional insights
- The README confirms:
- Angular CLI front-end at `localhost:4200`.
- Backend API server (Python/Java) at a configurable origin (default `localhost:8000`).
- CORS must allow the Angular origin.
- The UI is “built-in dev UI that comes along with ADK.”

##### Detail
- Break the Angular app into UI Components vs Core Services vs Directives/Utilities.
- Relationships among services (e.g. SessionService depends on HTTPClient and WebSocketService).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Application
    subgraph "Browser (Angular App)"
        direction TB
        subgraph "Bootstrap & Config"
            direction TB
            RC["runtime-config.json"]:::frontend
            IDX["index.html"]:::frontend
            MAIN["main.ts"]:::frontend
            APPCOMP["app.component.ts/html/scss"]:::frontend
            ROUTE["app-routing.module.ts"]:::frontend
            RC -->|fetches| RC
        end

        subgraph "UI Components"
            direction TB
            ART["artifact-tab/"]:::frontend
            EVAL["eval-tab/"]:::frontend
            EVENTT["event-tab/"]:::frontend
            SESSION["session-tab/"]:::frontend
            STATE["state-tab/"]:::frontend
            TRACE["trace-tab/"]:::frontend
            CHAT["chat-panel/"]:::frontend
            AUDIOCOMP["audio-player/"]:::frontend
            SIDE["side-panel/"]:::frontend
        end

        subgraph "Core Services"
            direction TB
            AGENT["agent.service.ts"]:::frontend
            EVALSVC["eval.service.ts"]:::frontend
            EVTS["event.service.ts"]:::frontend
            TRACESVC["trace.service.ts"]:::frontend
            SESS["session.service.ts"]:::frontend
            ARTSVC["artifact.service.ts"]:::frontend
            FLAG["feature-flag.service.ts"]:::frontend
            CHATSV["stream-chat.service.ts"]:::frontend
            WS["websocket.service.ts"]:::frontend
            AUREC["audio-recording.service.ts"]:::frontend
            AUPLAY["audio-playing.service.ts"]:::frontend
            DL["download.service.ts"]:::frontend
            LF["local-file.service.ts"]:::frontend
            UI["ui-state.service.ts"]:::frontend
            VID["video.service.ts"]:::frontend
        end

        subgraph "Directives & Utils"
            direction TB
            DIR1["resizable-bottom.directive.ts"]:::frontend
            DIR2["resizable-drawer.directive.ts"]:::frontend
            ENVUTIL["environment.ts / env.ts"]:::frontend
            RTV["runtime-config-util.ts"]:::frontend
            URLU["url-util.ts"]:::frontend
        end

        subgraph "Testing Utilities"
            direction TB
            TESTUTIL["testing/utils.ts"]:::frontend
            MOCKS["core/services/testing/"]:::frontend
            MODELTEST["core/models/testing/"]:::frontend
        end

        subgraph "Scripts & CI"
            direction TB
            CLI1["angular.json / tsconfig*.json / package.json"]:::frontend
            SCRIPTS["clean-backend.js / set-backend.js"]:::frontend
            CI[".github/workflows/angular-tests.yml"]:::frontend
        end
    end

    %% API Server
    subgraph "ADK API Server (Python/Java)" 
        direction TB
        REST["REST API Endpoints"]:::backend
        WSAPI["WebSocket Endpoint"]:::backend
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        MODELS["AI Model Hosts"]:::external
        STORAGE["Artifact/Media Storage"]:::external
    end

    %% Connections
    RC -->|HTTP| REST
    MAIN -->|bootstrap| RC
    ART -->|uses| ARTSVC
    EVAL -->|uses| EVALSVC
    EVENTT -->|uses| EVTS
    TRACE -->|uses| TRACESVC
    CHAT -->|uses| CHATSV
    SESS -->|uses| SESS
    AUDIOCOMP -->|uses| AUPLAY & AUREC
    SCRIPTS --> CLI1
    CLI1 -->|build/test| MAIN

    %% HTTP and WebSocket relations
    AGENT -->|HTTP| REST
    EVALSVC -->|HTTP| REST
    EVTS -->|HTTP| REST
    SESS -->|HTTP| REST
    ARTSVC -->|HTTP| REST
    WS -->|WS| WSAPI
    CHATSV -->|WS| WSAPI
    WSAPI -->|streams| TRACE

    REST -->|forwards| MODELS
    REST -->|stores| STORAGE
    WSAPI -->|forwards| MODELS
    WSAPI -->|stores| STORAGE

    %% Click Events
    click RC "https://github.com/google/adk-web/blob/main/src/assets/config/runtime-config.json"
    click IDX "https://github.com/google/adk-web/blob/main/src/index.html"
    click MAIN "https://github.com/google/adk-web/blob/main/src/main.ts"
    click APPCOMP "https://github.com/google/adk-web/blob/main/src/app/app.component.ts"
    click ROUTE "https://github.com/google/adk-web/blob/main/src/app/app-routing.module.ts"
    click ART "https://github.com/google/adk-web/tree/main/src/app/components/artifact-tab/"
    click EVAL "https://github.com/google/adk-web/tree/main/src/app/components/eval-tab/"
    click EVENTT "https://github.com/google/adk-web/tree/main/src/app/components/event-tab/"
    click SESSION "https://github.com/google/adk-web/tree/main/src/app/components/session-tab/"
    click STATE "https://github.com/google/adk-web/tree/main/src/app/components/state-tab/"
    click TRACE "https://github.com/google/adk-web/tree/main/src/app/components/trace-tab/"
    click CHAT "https://github.com/google/adk-web/tree/main/src/app/components/chat-panel/"
    click AUDIOCOMP "https://github.com/google/adk-web/tree/main/src/app/components/audio-player/"
    click SIDE "https://github.com/google/adk-web/tree/main/src/app/components/side-panel/"
    click AGENT "https://github.com/google/adk-web/blob/main/src/app/core/services/agent.service.ts"
    click EVALSVC "https://github.com/google/adk-web/blob/main/src/app/core/services/eval.service.ts"
    click EVTS "https://github.com/google/adk-web/blob/main/src/app/core/services/event.service.ts"
    click TRACESVC "https://github.com/google/adk-web/blob/main/src/app/core/services/trace.service.ts"
    click SESS "https://github.com/google/adk-web/blob/main/src/app/core/services/session.service.ts"
    click ARTSVC "https://github.com/google/adk-web/blob/main/src/app/core/services/artifact.service.ts"
    click FLAG "https://github.com/google/adk-web/blob/main/src/app/core/services/feature-flag.service.ts"
    click CHATSV "https://github.com/google/adk-web/blob/main/src/app/core/services/stream-chat.service.ts"
    click WS "https://github.com/google/adk-web/blob/main/src/app/core/services/websocket.service.ts"
    click AUREC "https://github.com/google/adk-web/blob/main/src/app/core/services/audio-recording.service.ts"
    click AUPLAY "https://github.com/google/adk-web/blob/main/src/app/core/services/audio-playing.service.ts"
    click DL "https://github.com/google/adk-web/blob/main/src/app/core/services/download.service.ts"
    click LF "https://github.com/google/adk-web/blob/main/src/app/core/services/local-file.service.ts"
    click UI "https://github.com/google/adk-web/blob/main/src/app/core/services/ui-state.service.ts"
    click VID "https://github.com/google/adk-web/blob/main/src/app/core/services/video.service.ts"
    click DIR1 "https://github.com/google/adk-web/blob/main/src/app/directives/resizable-bottom.directive.ts"
    click DIR2 "https://github.com/google/adk-web/blob/main/src/app/directives/resizable-drawer.directive.ts"
    click ENVUTIL "https://github.com/google/adk-web/blob/main/src/env/environment.ts"
    click RTV "https://github.com/google/adk-web/blob/main/src/utils/runtime-config-util.ts"
    click URLU "https://github.com/google/adk-web/blob/main/src/utils/url-util.ts"
    click TESTUTIL "https://github.com/google/adk-web/blob/main/src/app/testing/utils.ts"
    click MOCKS "https://github.com/google/adk-web/tree/main/src/app/core/services/testing/"
    click MODELTEST "https://github.com/google/adk-web/tree/main/src/app/core/models/testing/"
    click CLI1 "https://github.com/google/adk-web/blob/main/angular.json"
    click SCRIPTS "https://github.com/google/adk-web/blob/main/clean-backend.js"
    click CI "https://github.com/google/adk-web/blob/main/.github/workflows/angular-tests.yml"

    %% Styles
    classDef frontend fill:#D6E9FE,stroke:#1C6EF2,color:#0B2E6F;
    classDef backend fill:#E2F5E9,stroke:#2E8C3E,color:#155A23;
    classDef external fill:#F2F2F2,stroke:#999999,color:#333333;
```
