# polyai/adk architecture

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

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

## Overview

PolyAI ADK is a CLI for building, testing, and deploying voice and chat agents. The main workflow starts with project setup, then pulls and edits Agent Studio configuration, validates and pushes changes, and supports status, diff, branch, review, and deployment operations. Resource classes represent agent configuration; project management coordinates local files and remote synchronization through the API interface. The README documents chat, voice calling, metrics, and other capabilities. Some command implementations were not sampled, so their internal links are omitted or marked unverified.

Main entry points: [`src/poly/cli.py`](https://github.com/polyai/adk/blob/main/src/poly/cli.py) (CLI entry), [`src/poly/project.py`](https://github.com/polyai/adk/blob/main/src/poly/project.py) (Project manager), [`src/poly/resources/resource.py`](https://github.com/polyai/adk/blob/main/src/poly/resources/resource.py) (Resource model), [`src/poly/cli_commands/review.py`](https://github.com/polyai/adk/blob/main/src/poly/cli_commands/review.py) (Review commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and commands"]
  node_entry["CLI entry<br/>[cli.py]"]
  node_project_cmds["Project commands<br/>[project.py]"]
  node_sync_cmds["Sync commands<br/>[sync.py]"]
  node_branch_cmds["Branch commands<br/>[branch.py]"]
  node_deploy_cmds["Deployments<br/>[deployments.py]"]
  node_review_cmds["Review commands<br/>[review.py]"]
  node_chat_cmd["Chat command<br/>[chat.py]"]
  node_call_cmd["Call command<br/>[call.py]"]
  node_console["Terminal output<br/>[console.py]"]
  node_json["JSON output<br/>[json_output.py]"]
  node_metrics_cmd["Metrics commands<br/>[metrics.py]"]
  node_conversation_cmd["Conversations<br/>[conversations.py]"]
end

subgraph group_projects["Project workflow"]
  node_project["Project manager<br/>[project.py]"]
  node_validation["Push validation<br/>[prepush.py]"]
end

subgraph group_config["Agent configuration"]
  node_resource_model["Resource model<br/>[resource.py]"]
  node_flows["Flows and steps<br/>[flows.py]"]
  node_functions["Agent functions<br/>[function.py]"]
  node_entities["Entities<br/>[entities.py]"]
  node_resource_tools["Resource utilities<br/>[resource_utils.py]"]
end

subgraph group_services["Platform services"]
  node_api_interface["API interface<br/>[interface.py]"]
  node_platform_api["Platform API<br/>[platform_api.py]"]
  node_auth["Device login<br/>[device_flow.py]"]
  node_auth_handler["Auth provider<br/>[auth0_handler.py]"]
  node_github["GitHub API"]
end

subgraph group_runtime["Agent interaction"]
  node_chat_runtime["Chat session<br/>[chat.py]"]
  node_call_runtime["Voice call client<br/>[client.py]"]
end

node_user(("Developer"))
node_platform{{"Agent Studio"}}
node_github_service{{"GitHub Gists"}}

node_user -->|"runs"| node_entry
node_entry -->|"dispatches"| node_project_cmds
node_entry -->|"dispatches"| node_sync_cmds
node_entry -->|"dispatches"| node_branch_cmds
node_entry -->|"dispatches"| node_deploy_cmds
node_entry -->|"dispatches"| node_review_cmds
node_entry -->|"dispatches"| node_chat_cmd
node_entry -->|"dispatches"| node_call_cmd
node_entry -->|"dispatches"| node_metrics_cmd
node_entry -->|"dispatches"| node_conversation_cmd
node_project_cmds -.->|"manages"| node_project
node_sync_cmds -.->|"syncs"| node_project
node_branch_cmds -->|"manages branches"| node_project
node_deploy_cmds -->|"reads project"| node_project
node_review_cmds -->|"creates reviews"| node_github
node_review_cmds -->|"computes diffs"| node_project
node_github -->|"calls"| node_github_service
node_project -->|"uses API"| node_api_interface
node_project -->|"loads resources"| node_resource_model
node_project -->|"validates push"| node_validation
node_api_interface -->|"delegates"| node_platform_api
node_api_interface -.->|"transfers configuration"| node_platform
node_resource_model -->|"supports flow resources"| node_flows
node_resource_model -->|"supports function resources"| node_functions
node_resource_model -->|"uses utilities"| node_resource_tools
node_flows -->|"references"| node_entities
node_flows -->|"references"| node_functions
node_auth -.->|"requests tokens"| node_auth_handler
node_user -->|"signs in"| node_auth
node_chat_cmd -->|"starts agent chat"| node_platform
node_call_cmd -.->|"starts calling"| node_call_runtime
node_call_runtime -.->|"connects to agent"| node_platform
node_user -->|"views output"| node_console
node_user -->|"requests JSON"| node_json
node_metrics_cmd -->|"manages metrics"| node_platform
node_conversation_cmd -->|"manages conversations"| node_platform

click node_entry "https://github.com/polyai/adk/blob/main/src/poly/cli.py"
click node_project_cmds "https://github.com/polyai/adk/blob/main/src/poly/cli_commands/project.py"
click node_sync_cmds "https://github.com/polyai/adk/blob/main/src/poly/cli_commands/sync.py"
click node_branch_cmds "https://github.com/polyai/adk/blob/main/src/poly/cli_commands/branch.py"
click node_deploy_cmds "https://github.com/polyai/adk/blob/main/src/poly/cli_commands/deployments.py"
click node_review_cmds "https://github.com/polyai/adk/blob/main/src/poly/cli_commands/review.py"
click node_chat_cmd "https://github.com/polyai/adk/blob/main/src/poly/cli_commands/chat.py"
click node_call_cmd "https://github.com/polyai/adk/blob/main/src/poly/cli_commands/call.py"
click node_project "https://github.com/polyai/adk/blob/main/src/poly/project.py"
click node_validation "https://github.com/polyai/adk/blob/main/src/poly/utils/prepush.py"
click node_resource_model "https://github.com/polyai/adk/blob/main/src/poly/resources/resource.py"
click node_flows "https://github.com/polyai/adk/blob/main/src/poly/resources/flows.py"
click node_functions "https://github.com/polyai/adk/blob/main/src/poly/resources/function.py"
click node_entities "https://github.com/polyai/adk/blob/main/src/poly/resources/entities.py"
click node_resource_tools "https://github.com/polyai/adk/blob/main/src/poly/resources/resource_utils.py"
click node_api_interface "https://github.com/polyai/adk/blob/main/src/poly/handlers/interface.py"
click node_platform_api "https://github.com/polyai/adk/blob/main/src/poly/handlers/platform_api.py"
click node_auth "https://github.com/polyai/adk/blob/main/src/poly/auth/device_flow.py"
click node_auth_handler "https://github.com/polyai/adk/blob/main/src/poly/handlers/auth0_handler.py"
click node_github "https://github.com/polyai/adk/blob/main/src/poly/handlers/github_api_handler.py"
click node_console "https://github.com/polyai/adk/blob/main/src/poly/output/console.py"
click node_json "https://github.com/polyai/adk/blob/main/src/poly/output/json_output.py"
click node_chat_runtime "https://github.com/polyai/adk/blob/main/src/poly/cli_commands/chat.py"
click node_call_runtime "https://github.com/polyai/adk/blob/main/src/poly/call/client.py"
click node_metrics_cmd "https://github.com/polyai/adk/blob/main/src/poly/cli_commands/metrics.py"
click node_conversation_cmd "https://github.com/polyai/adk/blob/main/src/poly/cli_commands/conversations.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_project_cmds,node_sync_cmds,node_branch_cmds,node_deploy_cmds,node_review_cmds,node_chat_cmd,node_call_cmd,node_console,node_json,node_metrics_cmd,node_conversation_cmd toneBlue
class node_project,node_validation toneAmber
class node_resource_model,node_flows,node_functions,node_entities,node_resource_tools toneMint
class node_api_interface,node_platform_api,node_auth,node_auth_handler,node_github toneRose
class node_chat_runtime,node_call_runtime,node_user,node_platform,node_github_service toneIndigo
```

## Components

### CLI and commands

- [CLI entry](https://github.com/polyai/adk/blob/main/src/poly/cli.py): `src/poly/cli.py`
- [Project commands](https://github.com/polyai/adk/blob/main/src/poly/cli_commands/project.py): `src/poly/cli_commands/project.py`
- [Sync commands](https://github.com/polyai/adk/blob/main/src/poly/cli_commands/sync.py): `src/poly/cli_commands/sync.py`
- [Branch commands](https://github.com/polyai/adk/blob/main/src/poly/cli_commands/branch.py): `src/poly/cli_commands/branch.py`
- [Deployments](https://github.com/polyai/adk/blob/main/src/poly/cli_commands/deployments.py): `src/poly/cli_commands/deployments.py`
- [Review commands](https://github.com/polyai/adk/blob/main/src/poly/cli_commands/review.py): `src/poly/cli_commands/review.py`
- [Chat command](https://github.com/polyai/adk/blob/main/src/poly/cli_commands/chat.py): `src/poly/cli_commands/chat.py`
- [Call command](https://github.com/polyai/adk/blob/main/src/poly/cli_commands/call.py): `src/poly/cli_commands/call.py`
- [Terminal output](https://github.com/polyai/adk/blob/main/src/poly/output/console.py): `src/poly/output/console.py`
- [JSON output](https://github.com/polyai/adk/blob/main/src/poly/output/json_output.py): `src/poly/output/json_output.py`
- [Metrics commands](https://github.com/polyai/adk/blob/main/src/poly/cli_commands/metrics.py): `src/poly/cli_commands/metrics.py`
- [Conversations](https://github.com/polyai/adk/blob/main/src/poly/cli_commands/conversations.py): `src/poly/cli_commands/conversations.py`

### Project workflow

- [Project manager](https://github.com/polyai/adk/blob/main/src/poly/project.py): `src/poly/project.py`
- [Push validation](https://github.com/polyai/adk/blob/main/src/poly/utils/prepush.py): `src/poly/utils/prepush.py`

### Agent configuration

- [Resource model](https://github.com/polyai/adk/blob/main/src/poly/resources/resource.py): `src/poly/resources/resource.py`
- [Flows and steps](https://github.com/polyai/adk/blob/main/src/poly/resources/flows.py): `src/poly/resources/flows.py`
- [Agent functions](https://github.com/polyai/adk/blob/main/src/poly/resources/function.py): `src/poly/resources/function.py`
- [Entities](https://github.com/polyai/adk/blob/main/src/poly/resources/entities.py): `src/poly/resources/entities.py`
- [Resource utilities](https://github.com/polyai/adk/blob/main/src/poly/resources/resource_utils.py): `src/poly/resources/resource_utils.py`

### Platform services

- [API interface](https://github.com/polyai/adk/blob/main/src/poly/handlers/interface.py): `src/poly/handlers/interface.py`
- [Platform API](https://github.com/polyai/adk/blob/main/src/poly/handlers/platform_api.py): `src/poly/handlers/platform_api.py`
- [Device login](https://github.com/polyai/adk/blob/main/src/poly/auth/device_flow.py): `src/poly/auth/device_flow.py`
- [Auth provider](https://github.com/polyai/adk/blob/main/src/poly/handlers/auth0_handler.py): `src/poly/handlers/auth0_handler.py`
- [GitHub API](https://github.com/polyai/adk/blob/main/src/poly/handlers/github_api_handler.py): `src/poly/handlers/github_api_handler.py`

### Agent interaction

- [Chat session](https://github.com/polyai/adk/blob/main/src/poly/cli_commands/chat.py): `src/poly/cli_commands/chat.py`
- [Voice call client](https://github.com/polyai/adk/blob/main/src/poly/call/client.py): `src/poly/call/client.py`

### Other components

- **Developer**
- **Agent Studio**
- **GitHub Gists**

## Connections

- Developer → CLI entry: runs (evidence: `README.md`)
- CLI entry → Project commands: dispatches (evidence: `src/poly/cli.py`)
- CLI entry → Sync commands: dispatches (evidence: `src/poly/cli.py`)
- CLI entry → Branch commands: dispatches (evidence: `src/poly/cli.py`)
- CLI entry → Deployments: dispatches (evidence: `src/poly/cli.py`)
- CLI entry → Review commands: dispatches (evidence: `src/poly/cli.py`)
- CLI entry → Chat command: dispatches (evidence: `src/poly/cli.py`)
- CLI entry → Call command: dispatches (evidence: `src/poly/cli.py`)
- CLI entry → Metrics commands: dispatches (evidence: `src/poly/cli.py`)
- CLI entry → Conversations: dispatches (evidence: `src/poly/cli.py`)
- Project commands → Project manager: manages
- Sync commands → Project manager: syncs
- Branch commands → Project manager: manages branches (evidence: `src/poly/cli_commands/branch.py`)
- Deployments → Project manager: reads project (evidence: `src/poly/cli_commands/deployments.py`)
- Review commands → GitHub API: creates reviews (evidence: `src/poly/cli_commands/review.py`)
- Review commands → Project manager: computes diffs (evidence: `src/poly/cli_commands/review.py`)
- GitHub API → GitHub Gists: calls
- Project manager → API interface: uses API (evidence: `src/poly/project.py`)
- Project manager → Resource model: loads resources (evidence: `src/poly/project.py`)
- Project manager → Push validation: validates push (evidence: `src/poly/project.py`)
- API interface → Platform API: delegates (evidence: `src/poly/handlers/interface.py`)
- API interface → Agent Studio: transfers configuration
- Resource model → Flows and steps: supports flow resources (evidence: `src/poly/resources/resource.py`)
- Resource model → Agent functions: supports function resources (evidence: `src/poly/resources/resource.py`)
- Resource model → Resource utilities: uses utilities (evidence: `src/poly/resources/resource.py`)
- Flows and steps → Entities: references (evidence: `src/poly/resources/flows.py`)
- Flows and steps → Agent functions: references (evidence: `src/poly/resources/flows.py`)
- Device login → Auth provider: requests tokens (evidence: `src/poly/auth/device_flow.py`)
- Developer → Device login: signs in (evidence: `README.md`)
- Chat command → Agent Studio: starts agent chat (evidence: `README.md`)
- Call command → Voice call client: starts calling
- Voice call client → Agent Studio: connects to agent
- Developer → Terminal output: views output (evidence: `README.md`)
- Developer → JSON output: requests JSON (evidence: `src/poly/output/json_output.py`)
- Metrics commands → Agent Studio: manages metrics (evidence: `README.md`)
- Conversations → Agent Studio: manages conversations (evidence: `README.md`)
